
ICOM SIMULATIONS, INC. 


TMON 

PROFESSIONAL 


TUTORIAL 


The Advanced 

Macintosh 

Monitor/Debugger 







Ill 

ICOM SIMULATIONS, INC. 

presents 



TMON Professional 


Congratulations on your purchase of TMON Professional! TMON Professional provides 
far more power and sophistication than any previous member of the TMON family. To 
learn more about TMON Professional, see the Tutorial and Technical Reference manuals 
supplied with this package. This document provides a brief tour of the main files on the 
disks. It provides the simplest instructions on installation and mentions changes that 
occurred too late to be included in the manuals. 

TMON Professional comes on three disks. Insert “Disk One.” It should contain the 
following items; 


rxrrtn; 

§©! 

Release Notes 



TMON Startup 


CJ o 

TMON Extensions S-amples 



TeachText 


The “TMON Startup” file is an INIT or startup document which will load TMON when you 
restart your machine. 

The “TMON Extensions" folder contains several user areas which add functionality to 
TMON Professional, “dcmds” contains several useful dcmds to add features to TMON 
Professional. The “Sample TMON Settings” file is an example of a typical TMON 
settings file. This is covered below and in the Tutorial and Technical Reference manual. 
“Types” contains type templates for standard OS and ToolBox data structures, for 
example EventRecord. These templates can be used by memory windows to view and 
edit data in a formatted template. “ROMMap” allows TMON to associate labels with the 
routines and data in the various Macintosh ROMs. “Trap Record” defines how TMON 
records Traps and their parameters when you have Trap record enabled. “Trap Record” 
and “ROMMap” are both described in the Technical Reference Manual and Tutorial. 
“Commands Help” is a on-line help file which is documented later on in this document. 
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The “Samples” folder contains a sample application and its source which is used by the 
“Quickstart” section of the “Tutorial." It introduces several of the features of TMON 
Professional. 

“TeachText” is supplied to allow you to be able to read the various “Read Me” files 
supplied on the TMON Professional disks. If you already have a copy of “TeachText” on 
your hard drive you do not need to take a copy of this version. 


Installing TMON Professional 


Insert “Disk Two.” This second disk contains the TMON Professional application inside 
a folder labeled “TMON Folder.” Drag this folder into your system folder. Note: do not 
drag the TMON icon out of the folder. The “TMON Startup” file expects to find TMON and 
any TMON extensions inside the “TMON Folder” in your system folder. The only file 
which should be outside the “TMON Folder” is the “TMON Startup” file. 



TMON 


Insert “Disk One” again. Drag the “TMON Startup” file into your system folder. Now 
open the “TMON Extensions” folder and drag its entire contents into the “TMON Folder” 
which you placed in your system folder. 

You now need to configure TMON to your liking. An explanation of how to configure the 
basics for TMON is given below. 

On “Disk Three” you will find several other files which can be added to your “TMON 
Folder.” Leave these files until you have configured this initial TMON Professional 
installation. For more information on the files contained on “Disk Three” please refer 
to their specific documentation, which should be read before you attempt to install the 
files. 


Installing TMON Professional Under System 7.0 

System 7.0 installation is essentially the same as any previous systems, except for the 
following; 

Drag the “TMON Folder” into the “Extensions” folder in the your “System Folder.” 

Drag the “TMON Startup” file in the “Control Panels” folder which is also in the 
“System Folder.” 


Alternative Installation Method 

The “TMON” file is actually an application, which we refer to as the TMON loader. It is 
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used to configure the way in which TMON will operate. It also allows you to install and 
remove TMON from memory. TMON can still be installed by launching the TMON loader. 
The TMON loader will allocate space for the Monitor and install it and will also allow 
you to remove TMON from memory. For normal installation, use the TMON Startup loader 
(discussed below) in order for TMON to load when your machine boots. 


Configuring TMON Professional 



To configure TMON, simply launch the TMON application which is in the “TMON Folder” 
in your “System Folder.” 

When you launch TMON the window on the above right will appear. This window allows 
you to configure the TMON Settings file which TMON needs to load. The TMON 
application or control panel device (described below) will bring up the default options 
for a new TMON Settings file, if it cannot find a TMON Settings file in your “TMON 
Folder.” This file contains configuration information as well as a start up script of 
TMON commands which can be edited using the TMON application loader. This should be 
configured according to your needs. Among other things, this controls how much extra 
memory you wish to allocate to TMON. If you wish to open large source files and view 
them in TMON, you may wish to change the default TMON heap size. Please refer to the 
TMON Tutorial Manual for more information about configuring TMON Professional. 

Once you have configured TMON, quit the application answering “Yes” to any dialog 
requesting you to save changes to the “TMON Settings” file. This will create a “TMON 
Settings” file in the “TMON Folder.” You can now restart your machine. If all is well the 
TMON icon will appear at the bottom of the screen during startup. If you don’t get the 
TMON icon or if there seems to be a problem, refer to the TMON Professional 
documentation for an explanation of the various startup icons. 
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To enter TMON at INIT time, hold the option key down. To prevent TMON from loading 
automatically, hold the shift key or mouse button down, or move the TMON Startup 
loader into a different folder. Note: under System 7.0 onwards holding down the shift 
key at the start of the INIT or Extension loading process will cause none of the startup 
files to be loaded. 


TMON Control Panel 


TMON Startup 


Control Panel 


""X 


Mouse 


<11 

Sound 

on 


K> 


Startup Device 


TM0f4 Star'll 


K> 


3 . 3.2 


Wgk. Monitor 3.0 is present. 

826K used by the Monitor 

m _^bi 

Standard Monitor Settings 

Mode 

(•) Debug 

O Standby 

Loading Position 

(•) High memory 
O System heap 

Optional Data 
(8) Most 

O Minimal 

O Custom 1 
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SBfl 

K heap size 

fXl Load Monitor at startup 

CxH Let VBLs run 

[Xl Warn on vector changes 

Changes will 
take effect 
after a 
restart 


The “TMON Startup” file, as well as being a startup document, is also a control panel 
device (cdev). 

The above window is the TMON Control Panel. It allows you to obtain information about 
TMON, as well as change some of its configuration options. Please refer to the TMON 
Tutorial Manual for more information about using the TMON Control Panel. 

System 7.0 Virtual Memory and TMON 3.0 

TMON 3.0 is compatible with Apple’s Virtual Memory supplied with System 7.0. 
Nevertheless, there are a few special considerations for using TMON 3.0 with VM. See 
subsection 4.6.2 of the Technical Reference manual and below for the details. 

If you have only a small amount of real memory, you might encounter difficulties 
loading TMON at startup time; the memory available for TMON is less than half of the 
amount of physical memory you have minus the space taken for the system software 
and other system extensions (INITs). If you encounter a memory shortage, reduce the 
number of user areas and DCMDs you load with TMON and either increase or decrease the 
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Monitor’s heap size (see subsection 3.2.1 of the Technical Reference Manual). 

Please note that, since TMON is a low-level debugger, all memory allocated for the 
Monitor is physical; if you have a system with 2 megabytes of physical memory and 10 
megabytes of virtual memory and you allocate 1.5 megabytes for the Monitor, you will 
only have 0.5 megabytes of physical memory left to map the remaining 8.5 megabytes 
of virtual memory used for everything else; the system either will work very slowly or 
not at all. Don’t allocate a large amount of heap space for the Monitor just because you 
have a lot of virtual memory. 

If you are using VM, do not turn on the “Only trace below interrupt level” setting in the 
Options window. If you do, the Monitor will lose control while tracing, and your 
program will resume running at full speed. This problem is caused by VM’s increased 
protection of the processor trace bits. The practical consequences of this problem 
should be slight. 


Sample TMON Settings 



Sample TMON Settings 


The file “Sample TMON Settings” is in the “TMON Extensions” folder on “Disk One.” It is 
provided as an example of the sort of operations a startup script can perform. 

Although you can rename this file to “TMON Settings” and place it in the “TMON Folder” 
on your machine, it is recommended that you spend a few minutes configuring TMON to 
your particular needs. Please refer to the TMON Professional Tutorial Manual for more 
information about customizing your TMON settings file. 


TMON User Areas 


mllllIJif 

ttlllllllj 

ROMMap 

Trap Record 

mlllllllf 

mm'lllf 

Types 

dcmds 


The above icons represent TMON user areas. They are present in the “TMON Extensions” 
folder on “Disk One.” User areas are files which contain code and/or data which 
override or add functionality to TMON. User areas which you wish to use should be in 
your TMON Folder. In general, the more user areas that you have, the more memory TMON 
will consume. 


- 5 - 


Programmer’s Key 


HZ) 

Programmer's Key 


m 

Programmer's Key Notes 


This is the Programmer’s Key Startup document which is located in the “Programmer’s 
Key” folder on “Disk Three.” This allows for easy access to TMON from the keyboard. 
For instructions, read the “Programmer’s Key Notes” document. We highly recommend 
the use of Programmer’s Key. 


Commands Help 

“Commands Help” is a text file which contains help information for TMON’s command 
language. While learning to use TMON’s command language, it is useful to have this file 
as an on-line document. The document can be opened in a TMON View window for 
browsing without leaving TMON. 

To make things simple, the script of the “Sample TMON Settings” file has some 
commands defined to help you use this help file. The help command is invoked by the 
following: 

Syntax "chelp string>" 

To use this Syntax command, put the “Commands Help” file in your TMON Folder and 
copy the script commands from the “Sample TMON Settings” file to your own “TMON 
Settings” file. Note that Help is a reserved prefix for dcmds, and therefore Syntax has 
been defined as an alias to provide help for other commands. Syntax opens the View 
window to the “Commands Help” file, and searches for the specified help string. 

If the “Commands Help” file is in the TMON folder, and you added the support for it in 
your “TMON Settings” file, then you can bring up a Command window (which you can 
create with Command-Space) and get help with various TMON Commands. For example, 
type the following line in a Command window: 

Syntax "DeleteKey" 

This will open the file to a window describing TMON’s DeleteKey command. Note that 
typing quotes is necessary, since they are used to define a string which is being 
searched for in the “Commands Help” file. 

In addition to the Syntax command, a command key has been added to perform a find 
again function. Although the support for the “Commands Help” file was provided as an 
example in “Sample TMON Settings”, you may find it very useful in your everyday work. 

TMON Professional Disk Three Contents 
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=1 I...TMflM Pro. #3 .===== 

■HI! 

12 items 726K in disk 

41K available 

Q] Programmer's Key 

|° |TMON Interfaces 


o 

Qtmon fkey 

Q] TMON Actions f 



(° |TM0N XCMD 

|dcmds 



(°~~|TMON Stop Init 

f' [Discipline 



P ]Contributed Extensions f 

MacsBug Aliases f 


|° | Support j 

|^]MPW Scripts i 



<? 

2 

a 


“Disk Three” of TMON Professional contains many other items which you will find 
useful. Some of the files were contributed by beta testers who receive our thanks for 
their contributions throughout this product’s development. 

Addendum to using TMON Professional Memory Windows: 

Unlike Assembly windows and Dump Windows which take a single expression to 
indicate where they are displaying from memory, Memory windows can also accept a 
type template. Furthermore, advanced usage of Memory windows allows it to follow 
linked data structures by using another optional parameter. These additional 
parameters introduces complexities in the syntax of the Memory window. 

When using a Memory window as more than just a Dump window, you will also want to 
specify which type template to use. A few hundred are provided with TMON 
Professional in the "Types" user area. Thus to view a VBLTask record you may wish to 
type: 

New Memory VBLTask, (VBLQueue+2) 

Note that if you did not do this from a command line, but instead typed 
Command-Shift-M to make a new memory window, you would have to backspace TWICE 
before typing the arguments, once to delete the default address of $00000000, and then 
again to remove the colon Or alternatively, type Command-backarrow. This is an 
important point which may at first not be obvious. The colon is used to separate the 
template field from the offset field. 

If you wanted to look at the linked list of VBL tasks in memory then a third parameter 
is needed: 

New Memory VBLTask, (VBLQueue+2), A§ A 

See page 108 of the Technical Reference manual for a full discussion of the third 
parameter. If you create this Memory window or are scrolling through a memory 
window you will notice that the expression after the third parameter and subsequent 
colon is used as an address offset into the current template. 
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Chapter 1. Welcome! 

Welcome to the TMON Professional Tutorial. ICOM Simulations is proud to have 
you as a customer, and a user of the most powerful and most usable assembly level 
debugger for the Macintosh. TMON is designed to help you easily isolate and 
identify program defects that fall below the level of resolution visible with a 
source-level debugger. 


What is a Debugger? 

TMON is a program that is designed to help you track down problems in other 
programs that you may develop and run on die Macintosh. Debugging is a name 
for the process of isolating, identifying, and fixing software defects in a program. 
The debugging process often involves considerable amounts of time spent watching 
how specific sections of program code execute. 

True story: the term debugging comes from the early days of computing equipment. 
The technician charged with maintaining one of the now ancient and revered 
computer Goliaths discovered that a moth had disrupted the proper operation of 
the machine; the problem was fixed upon removing the moth (and repairing the 
damage). The moth was later taped to a page in the maintenance log book and 
became the first documented bug in the short history of computers. Because cute 
terminology was adopted quickly by what was at the time a tiny computer developer 
community, the term debugging was a near instant hit. 

TMON is much better at helping track down software “bugs” or defects in system, 
utility, or application code which are even rarer than insects getting caught in the 
equipment. TMON Professional’s job is to minimize the time that you spend 
debugging. 


TMON Professional vs. Source-Level Debuggers 

A source-level debugger is used to track down defects while working in the context 
of the target application program’s original implementation language. A Pascal 
programmer clearly prefers to use a debugger that understands Pascal code. A 
good high-level debugger will show the line in a Pascal procedure or function 
where a runtime error occurs, and it will display a meaningful error message like 
“Pointer not initialized before use.” It might even permit immediate editing of the 
source code. Source level debuggers are good for most programming errors that 
occur within a well-controlled, high-level-language development environment. 

There are times when the original source code is simply not around. In fact, 
sometimes the code is written in assembly language. Knowing how to debug when 
the source code isn’t around, or when the implementation language isn’t known, is 
a tricky problem. Note that the average Macintosh application relies on the vast 
amount of commonly-accessed operating environment code. This means that you 
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can spend more time studying what someone else’s code does than you spend 
debugging your own new code. 

TMON helps when the code you are having problems with isn’t yours. That is, you 
may not understand how to use a library function properly, or you think you do and 
it isn’t behaving the way you expected. 

TMON Professional Works With Raw Program Code 

TMON has the power to let you watch how any program works, not just programs 
that include debug information. You also don’t need to own or have the source of 
the program available. Because TMON can be used to debug any Macintosh 
program, TMON is often used to isolate problems with someone else’s (otherwise 
useful) program that, for example: 

Misbehaves when another program is present in the system 
Changes how the machine is configured 
Broadcasts an extra 15 bytes of data across a network 

TMON, being an assembly-level debugger, deals with problems that appear at the 
machine level of the computer, which is when no higher-level error checking code 
is present. The error messages that can appear are fundamental problems 
encountered by the system, such as a “Divide by Zero,” in which no sensible 
answer can be given by the system as a result of the calculation. The system has no 
other recourse but to attempt to display the Dire Straits Alert: 


Sorry, a system error occurred, 
diuide by zero 


(Restart) 


Fig 1.2 Dire Straits Alert 

If TMON is resident on the Macintosh when a fatal system error condition happens, 
TMON will start to execute in place of the Macintosh displaying the Dire Straits 
Alert. TMON has captured the state of the machine when the problem occurred. 

Less Overhead 

TMON doesn’t slow an application down quite like a source level debugger, but it 
has a noticeable effect. There are extravagant exceptions in TMON, where time is 
spent manipulating the application program’s operating environment to make it 
difficult for obscure errors to exist. Applications that rely on watching for external 
events, such as incoming data broadcast to a serial port, may fall behind while 
expensive debugging options are turned on. An example of a simple TMON 
command that generates a good deal of overhead as a side effect is 

Trace 0 
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The Trace command is one of the “single-step” commands you can use to walk 
through software an assembly instruction at a time; the particular form of the 
Trace command above permits the application code to execute continuously, but 
TMON intervenes after every instruction to check for break conditions, which never 
happens. Wow, does this slow things down: Quickdraw in Slo-Mo Instant Replay! 
The Trace command is described for you in chapter 8 of this Tutorial and chapter 
8 of the Technical Reference. 

Track Down Software Defects in Libraries 

Program developers often use commercially-available software libraries. Often 
these libraries (and their documentation) are well tested by the time you use them. 
Sometimes a library routine may be used incorrectly, or a software defect appears 
in a block of code in your program that you didn’t write, or you may know that the 
library routine couldn’t possibly be at fault—but you’d sure like to have a look at it 
anyway. For whatever reason, you don’t have source listings of that code; there 
often isn’t a source-level debugger-compatible version of the library. Your options 
look something like the following list 

Rely on the vendor for a timely repair 
Experiment until you fathom a workaround 
Wait for a software update 
Use TMON to find out what the problem is 

As mentioned before, using a source-level debugger when encountering a 
problem that you think may be caused by a commercially-available library, may be 
more difficult than investigating the code with TMON. Lacking a viable 
workaround, it is paramount to discover the cause of the problem, even when the 
code is being maintained by someone else. You may have to provide accurate, 
focused information to the people who are maintaining the problem code, and let 
them take care of the problem. 

TMON can be used to inspect the object code in libraries. Even though the original 
code may have been written in Pascal or C, TMON displays this and all other code 
as it exists on the Macintosh in assembly. 


What Else Does TMON Professional Do? 

As a low-level debugger, TMON provides the machine to you on a silver platter: 
you can step through executing code at your leisure, watch the CPU’s registers 
change value, and keep an eye on the contents of the heap zones, stack, resource 
file chains, and other system and application data structures. Few things in the 
Macintosh are too sacred for TMON, although things like high-volume real-time 
events are sometimes difficult to watch. 

Since the contents of some data structures and parameter lists are important, ways 
are provided to instruct TMON on what the legal values of fields in structures and 
lists should be. Because the Macintosh relies on data structures for even 
fundamental operations, automating the checking process goes a long way toward 
making TMON behave as a source-level tool. TMON makes use of, and displays 
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when possible the names and labels of identifiable resources, data areas, and 
executable code. You don’t have to know the hexadecimal RAM address of a 
routine to set a breakpoint there; you can refer to the routine by name. 

How Quickly Can I Come Up To Speed With TMON 
Professional? 

Higher-level computer languages are easier to read. Since assembly is a very low- 
level computer language (although the Motorola 68000 family of CPUs is better 
than most), it will take some time to learn how to debug using TMON because 
assembly is a verbose, tedious medium of expression. 

Fortunately, much of the debugging process involves examining trashed heaps, 
viewing system data structures, and other things that have little to do with 
assembly language. TMON can be very useful for exploring many parts of the 
Macintosh. For example, it is easy to examine resource file chains, see which 
resources are loaded or purged, examine the sizes of heap blocks, see how 
fragmented a heap is, force handle dereferencing problems to show themselves. A 
simple examination of a file’s resources can be a quick way to determine if a 
particular computer virus is present. 

It is important to note that although one may not be fluent enough to program in 
assembly language like a suave Apple systems programmer, you don’t have to be 
that good to control TMON and debug program code. Most of the errors that 
appear will turn out to be problems with interfaces between modules, programs, 
and functions: bad parameter list values, misplaced and mislabelled heap objects, 
values that are out of range, mismatched types or parameter counts, out-of-date 
structures—things that will require a keen eye to spot under any circumstances. 


What Good a Low-Level Debugger is to a High-Level 
Developer 

Some of the Macintosh code, particularly in the ROM, is implemented in assembly 
for speed considerations. High-level debuggers don’t meaningfully guide you 
through these areas. It is also possible that a high-level language compiler may 
generate bad code ; although the high-level source code looks perfectly fine from 
above, it isn’t the source code that is run by the machine, but the code generated by 
the compiler. For example, with a Pascal routine that makes use of a C function, if 
the Pascal and C compilers don’t agree perfectly with each other, a stack problem 
may occur that causes the program to stop working between source level statements. 

Sometimes a problem doesn’t occur immediately, but will wait at least a week or 
two, and then it will wait a few days before it happens again. The only successful 
way to track it down, it seems, is to let the program run and wait until it fails to get 
some good information on it. An application saddled with source-level debugging 
code in extreme cases may not be able to operate at a high enough capacity to 
entice the problem. TMON can be set up so that when a program bombs, the 
TMON monitor will kick in to display a great deal of useful information. 
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TMON provides ways to coax sporadic problems sooner than they normally would, 
such as scrambling the heap at your command, and Discipline, which insures that 
toolbox call parameters are set properly. 

Why TMON Professional is so Special 

We think that you are going to be pleased and surprised by all of the powerful 
features in TMON. Some of the most exciting features are: 

• Powerful Command Language 

TMON comes with a powerful and flexible scripting language. For example you can 
create a script that waits for a mouse click on any screen and then opens a memory 
window showing the pixel value where the mouse was clicked. 

• Sophisticated Pattern Matching 

TMON removes the need to type in a label by its exact name. If you know only part 
of the name you can always ask TMON to fill in the rest. 

• Supports all Motorola processors used in today’s Macintoshes 

This includes, of course, the 68020, 68030, and even the 68040, but it also includes 
the MMU (68851) and the FPU (68881 and 68882). 

• Supports System 7.0 

TMON takes advantage of System 7.0’s process manager, fully supports both 32 bit 
mode, and Apple’s virtual memory. 

• Data Templates 

TMON will let you look at data in just about any format that you want. 

• Menus and command keys are completely configurable and extensible. 

You can change TMON’s menus to anything you want. You can also attach a 
TMON script to any command key. 


Some Differences Between TMON Professional and 
TMON v2.8 

TMON has long been in development. We hope that users of earlier versions of 
TMON will like what we have done with the product. There are many new features 
and a large number of improvements to old ones. 

TMON continues to rely mostly on its own resources, and not on the Macintosh 
operating environment; it is crash resistant under dire circumstances when normal 
application software cannot operate properly. 

TMON windows still look a little different than regular Macintosh windows. They 
have been given many more features. Editing within TMON windows has 
improved. For example, standard Macintosh-like text editing has been made 
available. Another useful feature is smart-clicks which involve holding down 
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modifier keys and clicking on specific contents in a TMON monitor window to 
invoke a TMON operation. One example is opening a new assembly window using 
a clicked-on address. Another hot example is setting a breakpoint at the clicked-on 
address and exiting TMON. 

Window updating is more often and more intelligent. They can be sized in the 
vertical direction ala Macintosh windows and TMON 2.8, and now in the horizontal 
direction using the TMON Options window. Windows can be steered to any screen 
on a multiple-screen system. 

Command expressions in TMON are now very powerful. They can include 
hexadecimal, decimal, and binary numbers, ASCII values, arithmetic and boolean 
operations, labels and trap names, like the old versions. Expressions can be re¬ 
evaluated automatically, for example, whenever the program counter changes. 
TMON windows dynamically update when expressions are re-evaluated. 

C operators, including logical shifts, boolean and logical operations, and 
conditionals are supported. Strings and labels are supported well ; for example, 
TMON knows and displays the names for most Low-memory globals. Instructions 
for all Motorola processors that have been used in Macintoshes are fully supported. 
Floating point is supported well, including numeric and hex editing, arithmetic, trig, 
and algebraic operations. Future processors are anticipated. 

TMON has more powerful, flexible heap and file inspection capabilities. 

Breakpoints, trap watching, recording, tracing, and stepping are probably 
unrecognizable to users of TMON 2.8. 

Startup and configuration of TMON is handled by a descriptive set of dialogs in the 
TMON loader. 

Most importantly, much of this new TMON is written in the high-level language 
C++, making updates, changes, and corrections much easier to do. It is now a much 
simpler task to deal with Macintosh system changes and get updates out to 
developers. 

This new TMON is also much easier for you to extend. 

The exhaustive list of the new and modified TMON features is in Chapter 1 of the 
TMON Professional Reference Manual. 


About The TMON Professional Manuals 

There are two parts to the TMON Professional manual. The Tutorial introduces all 
the major features and commonly used windows of the debugger, emphasizing 
interactive use. It provides a large number of examples and screen shots 
throughout except Chapter 3. Chapter 3 is the TMON Quickstart, a fast guided tour 
of a wide spectrum of the debugger; it walks you through a number of features, but 
is completely devoid of screen shots. 
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The Technical Reference is a technical description of.TMON. The Technical 
Reference leaves the description of the interactive operations to the Tutorial, and 
instead completely covers the underlying script language. Every command invoked 
through a TMON window is covered by a script command. Some TMON 
commands are very esoteric, and are given only passing mention by the Tutorial. 

Most developers will initially use the Tutorial but will gradually become familiar 
with the Technical Reference . 


In Summary 

High-level debugging is best handled by source-level debuggers. TMON is not a 
replacement for high-level debuggers, but an extension to them. TMON takes over 
where the high level debuggers leave off. There are many useful things that can be 
done with TMON that do not require a deep understanding of assembly language. 
TMON is a surprisingly sophisticated symbolic debugging system that is much 
improved over TMON version 2.8. The TMON manual has two. big parts, the 
Tutorial and the Technical Reference. The Tutorial contains the Quickstart, a walk 
through of a few of TMON features. 
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Most of this chapter is dedicated to getting your copy of TMON up and running 
^ e11 ®“™£*Lf°r you to learn how to use it. The installation procedure provided by 
the 1MON Technical Reference Manual is something else again; it goes into detail 
about everything, including what to do when TMON doesn’t appear to work and is 
great for delving into TMON configuration arcana. 

Start by copying the TMON Master Diskettes onto the backup volume of your 
choice. We Mean It, Make A Backup Copy NOW. This is a debugger you’re dealing 
with, not an accounts receivable package. TMON has more lives than a cat, but it 
has only so much armor plating and is daily asked to perform beyond the limits of 
the unexpected. Please be certain that on your master and backup diskettes you 
can see through the write-protect slot. 


What Kind of Macintosh Do You Have? 


I h l re "i° n T ^f k 1S k ecause TMON does not operate with Macintoshes equipped 
with 64K ROMs and requires at least 1 Meg of RAM, although 2 Meg are 
n e A C ^ lm< i' nC > ' ( ' Machines so equipped include the original Macintosh (with 128K of 
RAM) which was released in the year 1984, and the Macintosh 512. That is any 
Macintosh re eased before the Macintosh 512KE. Anything else is fine, including 
a/T Macintosh II we knew about before the release of TMON: Macintosh II Ilex 
Ilci, Ilfx IIx, IIsi. TMON works fine on a Macintosh Plus, Macintosh SE, Macintosh 
Classic, Macintosh LC, and Portable. 


In the case of a 64K ROM machine or less than 1 Meg of RAM, we recommend that 
you continue to use TMON 2.8. 


How Much Memory Do You Have? 

TMON needs more memoiy than TMON 2.8 ever did; a Macintosh system with 2 
megabytes or more is recommended. However, TMON can be configured to run in 
400K which allows it to work, just barely, in a Macintosh with one megabyte of 
memory. J 
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What System Software are You Using? 

TMON has been extensively tested to work with the following: 

• System 6.0.3 or later. Earlier System files such as 5.X or 6.0 may not 
operate properly. 

• System 7.0. 

• 32-bit system software. 

• Apple virtual memory. 


Do You Have Another Debugging System Installed? 

TMON can recognize when an assembly-level debugger is installed in a system 
and warn you of its presence. TMON Pro’s effectiveness may be drastically 
hampered by the presence of another low-level debugger; it is recommended that 
they be removed before installing TMON. TMON, like any other debugging facility 
of its kind, is designed to be in control. Having two such programs competing for 
control of your system is to be avoided. 

TMON works well with the Symantec Think and the Apple SADE debuggers. 

Into The System Folder with it, Har Har! 

Here are the minimum number of files and folders that need to be placed in the 
System Folder of the Macintosh Startup Disk for System 6 (remember, after 
System 6.0.3): 



Figure 2.1 Where Folders and Files Go 
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For System 7, the TMON Startup file should go into the Control Panels 
folder, and TMON Folder and Programmer's Key in the Extensions folder 
within the System Folder. There is some backward compatibility in System 7.0 
so that documents residing in System Folder under System 6 can still be placed 
there, and not necessarily in one of the new folders within System Folder. 

There are several other files contained on the distribution disks. This Tutorial 
introduces them one at a time throughout the text, but if you are curious about 
what they all do and where they can go, check out chapter 2 of the Technical 
Reference. We’ll wait. 

On TMON disk one, you will find the tmon startup control panel (and INIT) file. 
The Programmer's Key Startup Document is in the programmer’s key folder on 
disk three. On TMON disk two you will find the tmon Folder inside which you 
will ONLY find tmon. You have no tmon Settings file because it isn’t provided 
on the distribution disks, and you haven’t created it with tmon yet. 

There are two ways to start TMON: automatically at system start up, and manually 
by double-clicking the TMON icon. When TMON automatically starts, a TMON 
start up icon will appear at the bottom of the Macintosh screen; and that’s it. All the 
possible start up icons are shown below. Manual activation on the other hand 
brings up the TMON loader, which displays a dialog with a few buttons. 

TMON Professional is installed 



rKJXk TMON Professional was not not installed (e.g. Shift key held 
TjkIKJF down) 



TMON Professional was not installed because the TMON 
application could not be found 



TMON Professional was not installed because the TMON 
Settings document could not be found 



TMON Professional was not installed because there was not 
enough memory for the current configuration 


TMON Professional was not installed due to an error; you 
can attempt to install TMON Professional manually to 
determine what the error is 

No Icon TMON Professional was not installed because it was 
configured not to load on startup, or TMON Startup is in the 
wrong place) 
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Creating the TMON Settings File 

Since TMON refuses to automatically start at system boot time until a TMON 
Settings file has been created, you must create a TMON Settings file. A tmon 
S ettings file contains the loading and configuration settings for TMON. Enter 
the TMON loader by double-clicking on tmon after all the other files have been 
copied onto your startup disk in the arrangement shown in Figure 2.1. Follow the 
next few sections to create a tmon Settings file. 

Preventing Automatic TMON Professional Startup 

One way to prevent TMON from starting at boot time is to move the TMON Startup 
file into the TMON Folder. The Macintosh operating system (Version 6, mind you) 
only executes INITs that are directly in the System Folder, and not in a folder in the 
System Folder. System 7 has backward compatibility with System 6, and will also 
look in some folders within the System Folder, like the Control Panels folder. 

Another way to prevent TMON (and the Programmer’s Key, for that matter) from 
installing is by holding down the shift key or the mouse button during start up. This 
method must be done each time the system is restarted unless you resort to a more 
permanent method. 

A third way is to enter the TMON loader and set the control in the appropriate 
dialog. This method is described shortly, and its effect is however long you leave it 
set like that. 

A fourth way is to set the appropriate checkbox in the TMON control panel. The 
control panel is described briefly at the end of this chapter. This is the same 
control, actually, as the third method just described, but access is a little more 
straightforward in normal use. 
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TMON Professional Configuration 

Double-clicking the TMON application (or a TMON Settings document) will start 
the TMON Professional loader, which will display the TMON Settings dialog box: 


=□===== TMON Settinas 1 

ff 

] Standard Monitor Settings 

<§ 

1 Debugging mode 


\m\ 

Load the Monitor on system 
startup 

M 

Allocate 256K for the 
i Monitor heap 

Load the Monitor into high 
memory if possible 

i 

8 

Allocate 16K for the Monitor 
stack 

Let VBL tasks run while the 
Ww Monitor is active 

Load most optional data 

Nlllllllli 

1 

1 


Warn on exception vector 
^ changes 


Edit script 


Figure 2.2 Default TMON Professional Loader Settings Dialog 

Each of the rectangular areas is a button except for the top one labelled Standard 
Monitor Settings. Selecting any button will bring up another dialog box, each of 
which contains some description and a control for an adjustable TMON option. 

The menu bar has two decidedly TMON Professional menus: Settings and 
Monitor. TMON also adds two unique entries to the File menu for manually 
installing and removing the TMON monitor from the system. The menu items in 
the Settings menu duplicate the buttons in the TMON Settings dialog. The 
Monitor menu permits you to manually enter the TMON monitor, and to see how 
memory is allocated for a currently installed TMON. 
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Figure 2.3 TMON Professional Loader Menus 

To save a default TMON configuration in a new TMON Settings document in TMON 
Folder, select the Saue or Saue fls... menu items under the File menu. The 
configuration shown above should be acceptable for now. 

Installing and Removing the Monitor 

You can manually install TMON Professional by selecting the Install Monitor 
menu item in the File menu of the settings document. Just under Install 
Monitor is Remoue Monitor; one or the other menu item is greyed out at a 
given moment. 

Entering the TMON Professional Monitor 

One way to bring up the TMON monitor is to select the Enter Monitor menu 
item in the Monitor menu. This is the long way about it in normal practice, but it 
comes in handy when you are tuning TMON by interactively changing the settings 
document. You can only enter TMON after the debugger has been installed, and 
TMON has to be removed and reinstalled for changes made in the settings to be 
noticed. 

The Technical Reference contains extensive troubleshooting information in Chapter 
2 in case you run into difficulties. 
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Debugging Mode 

Select the Debugging Mode button in the Settings Dialog, or by selecting the 
Mode menu item in the Settings menu, to get this dialog box. You get two 
configurations to select from: Debug, which means that you intend to actively chase 
bugs and are going to need all or most of TMON’s features; and standby, which is 
intended to provide a skeletal TMON in memory just in case a crash happens. 
Debugging mode is guaranteed to need much more memory than Standby mode. 

Some problems may require a full Debugging Mode version of TMON to track 
down, despite their sporadic nature. Standby mode is intended to track down very 
n cidents, well after the majority of defects have already been solved. Although 
lull debug is better prepared for such work, it needs more memory. 


Choose “Debug” to use the Monitor primarily for 
debugging. Choose “Standby” to keep the 
Monitor in the background just in case the 
system crashes. This option affects all other 
configuration options. 


(•) Debug 
O Standby 


| OK' | ( Cancel 


Figure 2.4 Standard Monitor Settings 
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Debugging/Standby Mode affects the entire configuration of TMON, and also what 
the other buttons show. Here’s a look at the TMON Settings Dialog when standby 
mode is selected: 


=n=°= ::; s TMON Settings ■ =—= = gg 

Standard Monitor Settings 

< 

Standby mode 

tag) 1 Load the Monitor on system 
— startup 

Allocate 64K for the Monitor 

Load the Monitor into high 
ullllr memory if possible 

1 

‘ ’ffl Allocate 1 6K for the Monitor 
Hst stack 

Let VBL tasks run while the 
Monitor is active 

^t?9? Load minimal optional data 

'nttlnttf 

Oo not warn on exception 
^jQjk, vector changes 



[ 

gr_. Edit script 


Figure 2.5 Standby Mode Settings 

Monitor Heap 

The TMON monitor needs heap for numerous reasons. For example, TMON 
windows are created in the heap; a larger heap will permit more and bigger 
windows. Developers who have large screens or color displays will probably want to 
allocate more heap than the default 256K provided. If the TMON view command is 
used, the heap may have to be enlarged to show bigger files. Elaborate scripts with 
hundreds of macros require more heap space. 



Choose the number of kilobytes 
that the Monitor should allocate 
for its heap. (48K minimum) 


256 

K 

-- 

OK | 

Cancel 

- J 


Figure 2.6 Monitor Heap Dialog 
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Monitor Stack 


16K of stack space is sufficient for most needs, including 
scripts, large displays, and numerous windows. 


the demands of elaborate 



Choose the number of kilobytes 
that the Monitor should allocate 
for its stack. (16K minimum) 


Cancel 




Figure 2.7 Monitor Stack Dialog 
Optional Data 

There are four optional data settings provided for in the Optional Data dialog. 
Knowing the difference between any of them demands your understanding of 
which features in TMON are vital rather than merely nice, much less what each 
feature can do. Section 2.2.5 of the Technical Reference covers the essentials quite 
well if you are well-versed in low-level Macintosh work and want to know specifics. 

In general, the four options work this way: 


Load most 
Load minimal 
Custom 1 
Custom 2 


Provides most optional data and extensions 

Provides a stripped debugging facility 

Initially set up as the same as Load most optional data 

Initially set up to load all optional data and every extension 


Custom 1 and 2 are yours to redefine. Go wild. Specific instructions for doing this 
are provided in section 2.2.5 and Chapter 9 of the Technical Reference. 


If you don’t have a memory limitation, select the default, Load most optional 
data and go on to the next configuration dialog. Developers using machines with 
less than two megabytes will likely want to remove the amount of space occupied 
by TMON; the memory difference between Load most and Load minimal is 
significant, but consequently so are the debugging resources available to you. 
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Choose how much optional data you want loaded 
’Hi with the Monitor. The more optional data you 
load, the more useful the Monitor will be, but it 
will also require more memory. 


<•) Load most optional data 
OLoad minimal optional data 
O Custom 1 

O Custom 2 (all optional data) 


(Cancel ] 


Figure 2.8 Optional Data Dialog 

User Areas 

TMON user areas are contained in the other files normally kept in TMON Folder. 
They can be used to add a wide variety of additional debugging capabilities to 
TMON, such as type templates, DCMDs, and trap recording message strings and 
formats. User areas are discussed in detail in the reference manual. User area 
documents are represented by this icon: 


User Area Name 

User areas are mentioned here because their presence in memory is partially 
controlled by this window (most of the user areas are considered to be optional, and 
aren’t loaded when you set this option to load minimal optional data). You can 
directly prevent user areas from being loaded into RAM by simply removing them 
from the TMON Folder. 

Installing TMON Professional at System Startup 

For TMON to be automatically installed under System 6.X, all of the following must 
be true: 

• Documents TMON and TMON Settings are in TMON Folder, which in 
turn is in System Folder 

• TMON Startup is in System Folder 

• In the TMON loader, L o a d M o n i t o r in the Load Monitor dialog must be 
selected (See Figure 2.9) 

Because there are three basic conditions for everything to work, it is sometimes 
easy to forget that you did something that kept TMON from being installed. You 
start testing only to discover TMON wasn’t around to protect you from the Dire 
Straits Alert. 
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If the TMON Startup file is present in the System 
Folder, the Monitor will be automatically loaded 
wheneuer the Macintosh starts up unless you 
hold down the shift key or the mouse button or 
disable this option. 


Load Monitor at startup || OK jj f Cancel) 


Figure 2.9 System Startup Time Load Dialog 

Where TMON Professional is Installed in Memory 

The TMON Loading dialog provides two ways to place TMON in RAM: in high 
memory and in the system heap. 

When TMON is loaded in high memory, it is above all application code, data, and 
stacks, where it is a harder target for wayward applications to clobber. The 
drawback to high memory usage: there may be a problem with reinstalling TMON 
in high memory when you remove TMON to reconfigure it; this depends on how 
you use the system. Also, an errant application might clobber high memory, so it is 
sometimes necessary to switch TMON to another memory location. 

When installed in the system heap, TMON is in a nonrelocatable block, and it is 
pretty easy to take out and reinstall. This is because system heap memory is 
controlled by the Memory Manager and therefore can be easily allocated and 
deallocated. On the other hand, high memory is not controlled by the Memory 
Manager and therefore it is difficult to re-use without rebooting 

If you do not understand the difference between these two options, do not worry, it 
normally is not important. 

When manually installed, TMON is always loaded in the system heap when 
MultiFinder is operating; it is important to note that at start up time installation 
occurs before MultiFinder kicks in. TMON is also placed in the system heap when in 
a 24-bit environment with more than 8 meg of virtual memory. When the system 
heap must be used, the Load dialog box setting is ignored. 


Choose the place into which the Monitor is 
loaded. Howeuer, when MultiFinder is present, 
the Monitor will be loaded into the system heap 
regardless of this setting. 

<•) High memory 
O System heap 


[( OK ]| (Cancel) 


Figure 2.10 TMON Professional Monitor Loading Options 
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For more gory details on TMON Installation including error messages, peruse 
sections 2.2.7 and 2.3 of the Technical Reference. 

VBL Tasks 

Normally, VBL (Vertical BLanking interval) tasks will continue to crank along, even 
when the application has ground to a halt and TMON appears on screen. There are 
times when this can be had, such as when the VBL task is processing data 
continuously broadcast to your machine—by the time the rest of the program is 
permitted to continue on its way, all of memory could be filled with queued packets. 

Also, if you are debugging a VBL, then you probably want to suspend them. 


Choose “Suspend UBLs” if you are debugging 
code that uses unreliable uertical blanking 
tasks. This preuents these tasks from crashing 
the Monitor. Choose “Leaue UBLs running” for 
normal operation. 

OSuspend UBLs > y _ 

If OK ]| (Cancel 
(•) Leaue UBLs running V . 9 - 


Figure 2.11 VBL Task Mode Dialog 
Exception Vector Changes 

TMON Depends on low-memory exception vectors in order to stay alive and 
healthy. You can discover inadvertent changes to exception vectors by periodically 
checking them with TMON. TMON does not normally automatically kick on when 
a vector change has been made, unless it leads to a recognizably bad situation. With 
the Vector Warning option enabled, TMON will check these exception vectors (and 
if necessary display an alert) every time it is entered. This dialog is a way to select 
whether TMON checks the exception vectors. 



Choose “ILlarn on uector changes” to haue the 
Monitor display a uuarning mheneuer enception 
uectors are altered. Altered enception uectors 
may indicate a bug, but some applications may 
intentionally alter them. 


® UJarn on uector changes 



(Cancel) 


Figure 2.12 Exception Vector Change Warning Dialog 
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Startup Script Edit Window 

Defining script commands is easy. When the script edit button is selected, a text 
edit window opens, showing the data fork of the TMON Settings file. By default, the 
data fork contains an empty script. 

The empty script should not get in your way as you learn TMON. It is an excellent 
place to make additions and changes to the default TMON script commands. A bad 
place to make the same changes is in the data fork of the TMON file itself, which is 
where all of the standard command aliases, menu items, keys, macros, and 
variables are defined using TMON script commands. We strongly recommend that 
you take the time to look at the TMON data fork with the TMON view command, 
but don’t touch. 

As a matter of fact, each of the user area files can also contain a data fork that can 
also hold any number of script commands. These script commands are 
appropriately associated with the contents of the user area file, and shouldn’t need 
to be modified. 

Script commands can be selected and evaluated if TMON is installed, making 
testing and debugging easier. This is similar to script command selection and 
execution using MPW shell windows. 

Figure 2.13 shows the top part of a sample TMON Settings file edit script Feel free 
to explore. 


TMON Settings 


10 


|//// Define screen a I iases, and set screen for T110N to use 

alias Screen 1,"Options /screen=1 dn Uars DscreenBottom=.870" 
alias Screen2, "Opt i ons /screen=2 dn Uars DscreenBottom=.48Q" 
alias Screen3,"Options /screen=3 dn Uars DscreenBottom=.480" 




Options /MaxWidth=.683 
Screen 1 


// Don ’ t make u> i ndows too b i g 


////////////////////// Window configuration support ///////////, 

alias lnitWind,i 
“Close alii 
Uars CmenuSize=.60 S 
Uars OwindGap=-.1 d 
Uars D(uindExtra=.5 d 
Uars DlineHeight=.10 i 
Uars OcurWTop=DmenuSize d 
Uars OcurUBo t tom= DscreenBo t tom" 


EE 






0 


Figure 2.13 TMON Professional Script Editor Window 

Installed Monitor Information Dialogs 

The Get Info menu item under the Monitor menu leads to a dialog that provides 
current information on the debugger currently loaded into RAM. This means, for 
example, that it will attempt to identify the type of debugging system loaded—it 
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doesn’t have to be TMON. This dialog shows pertinent information on the following 
debuggers: 

TMON Professional Version 3 
TMON Version 2 
MacsBug 
Other 

If TMON is installed, the following dialog will be displayed: 



Monitor 3.0 is present. Its memory usage is as 
follows: 




16384 bytes for the Monitor stack. 

18520 bytes for globals. 

7884 bytes for the jump table. 

239414 bytes for Monitor's and user areas' code. 
136030 bytes for static data. 

41372 bytes for uolatile data. 

412 bytes for purgeable data. 

202784 bytes free. 

662800 bytes total. f[ OK j) 


Figure 2.15 TMON Professional Info Dialog 
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If TMON version 2 is loaded in RAM, then this next dialog is used: 


TMON 2 is present. Its memory usage is as 
follows: 

19904 bytes for the Monitor code. 

6656 bytes for flOOO trap name routines. 

4096 bytes for Monitor’s uariables and local stack. 
32256 bytes for the User Area (physical size). 

30740 bytes for the saued screen and cursor. 

93652 bytes total. if 


Figure 2.16 TMON Version 2 Information Dialog 
If MacsBug is loaded, then this incredibly informational dialog is used: 


MacsBug is present. 


[( OK 





Figure 2.17 MacsBug Dialog 

Lastly, the TMON settings document can detect an unknown debugger even 
though it can’t identify the exact brand: 



Figure 2.18 Other Dialog 
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TMON Professional Control Panel 


Another way to configure TMON is by using its Control Panel, available when the 
TMON Startup document is in the System Folder (for System 6.0.3 and later 
versions of System 6). If you are using System 7, this file is placed in in the 
Control Panels folder. 

The TMON control panel shows what the current memory allocation looks like and 
a few of the other configurable options available through the TMON loader. The 
memory usage bar uses the same patterns as the TMON Get Info dialog box shown 
a couple of pages ago. 


Control Panel 




Mouse 


< 1 # 

Sound 

5J 


K> 


Startup Device 


TMONStartu 


5.5.5 



Monitor 5.0 is present. 
647K used by the Monitor 


Standard Monitor Settings 


Mode 

Loading Position 

Optional Data 

{•) Debug 

O Standby 

0 High memory 
O System heap 

(•) Most 

O Minimal 
O Custom 1 
O Custom 2 

11256 J 

K heap size 

1 Load Monitor at startup 

. 3 Let VBLs run 

2 3 Warn on vector changes 

Changes will 
take effect 
after a 
restart 


Figure 2.19 Control Panel 
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Quickstart 


Quickstart is a short tour of some key TMON features. It is by design short 
contained m a very few number of pages. You don’t have to be an etferflsoftware 

S?5 ei 7° ^ the f Qu i ck f tart > b ut if parts of it don’t make sense or contain an 
unsatisfactory amount of information, the location in the Tutorial or Reference 
where more detail can be found is mentioned in the second column. 

S?Tw& USe S a u exan ] pl e program, provided on the distribution disk, as part of 
otherSl ^ k hr ° Ugh ' T ° keeP Quickstart short > k is free of illustrations and 


Start TMON Professional Up 


S e flnJiS ng »t^ neral lo ; k ?!™? N >>? first racing the minimum number 
files and folders that are needed into the Mac’s System Folder to make TMON 


Install TMON Professional 


Drag Programmer’s Key, TMON Startup, and the TMON 
Folder to your System Folder. Double-click on TMON to 
start the TMON Loader. Select Saue to create a default 
TMON Settings file. Quit. Reboot. 


TechRef 1.3, 
2.3, 3.2 

Tutorial 2 


Machines without an interrupt switch on the front or side 
will definitely need to have Programmer’s Key installed. 

Enter TMON Professional 


On ADB keyboards with Programmer’s Key installed, 
press Option-POWER key; otherwise, when available, 
press the Option key and the interrupt switch on the side 
(or front) of the Macintosh at the same time. 


TechRef 2, 3.1, 
3.2 

Tutorial 2, 4 


The option key uses TMON’s trap signal mechanism for 
entering TMON at a “clean time” such as 
GetNextEvent, instead of at the exact time of the 
interrupt, when the machine may be in an inconsistent 
state (e.g. in the middle of a heap compaction). 
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Exit TMON Professional 

There are three easy ways to do this: click on the Exit 
button on top of the screen; or type S€-E; or type 8€- 
SPACE to bring up the Command window at the bottom of 
the screen, type exit and then press the Return key. 

More involved ways exist when using TMON commands 
to trace through code, and are discussed at length in both 
manuals. 

Start the Sample Program 

Insert a copy of your original TMON disk with the 
Samples folder and double-click on one of the Sample 
applications. You are given a choice between a Pascal, C, 
and an Assembly version. 

Press Option-POWER key, or press the interrupt switch 
on the Macintosh and the Option key to enter TMON. 

TMON always starts with a message at the top of the 
screen. Click once to clear the message. 

Window Interactions 

Now is a good time to familiarize yourself with TMON’s 
windows. For our purposes here, just about any window w 
ill do, so click on the assembly menu command (3€-A)to 
create an assembly window. 

Try dragging the window up and down. Try resizing it. 
Click on the down arrow control to scroll it. Click on the 
double-down-arrow control to page the window. 

Editing and Selecting Text 

Click and hold the button down in the assembly window 
on an instruction, and drag to the right. Notice that 
editable areas allow for text selection in a way that 
Macintosh users are accustomed to. 

Moving the Cursor Home 

Press the Tab key. This always brings you to the top of 
the current window. In this case it should be the top of the 
assembly window. 

Finally, click on the go-away box (upper left hand corner) 
to make the window disappear. 


TechRef 8.3.3 

Tutorial 4, 8 
(Exit Options) 


TechRef 4.2.4 
Tutorial 4 


TechRef 4.3 
Tutorial 4 

TechRef 4.2 
Tutorial 4 
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The Most Popular Features 

Most developers will make a beeline for the obvious features: how TMON 
disassembles code, breakpoints, and tracing. So, OK: here’s the Really Neat Stuff. 


Intercepting OS and Toolbox Calls 


Press 3€-T to open a Traps window. Now type _alert, 
and press Return. A new entry in this Traps window 
appears with the trap name _Alert (you might have to 
resize the Traps window to see it). Of the options listed on 
the left of the entry, only the Intercept (I) flag is set. Select 
the Exit menu item (§€—e) to leave TMON with the 
current program still running. 


TechRef 7.2.2 

Tutorial 8 
(Recording, 
Traps, and 
Breakpoints) 


In the sample application, select the Rbout Sample... 
menu item. TMON should reappear with the message 
Trap intercepted at (some address). 


Press - T again, just in case the Traps window is no 
longer the active one. Type clear alert and press 
Return. This should remove the _Alert entry in the 
traps window. 


Find a Symbol in the Assembly Window 


Type 


3€-A 


to select or create an assembly (really an assembly and a 
disassembly) window. Now type setl..., and press 
Return. Important note: the “...” is the ellipsis character, 
(Option- ;) it is not three periods. 


TechRef 4.2 
4.3, 7.1.2 

Tutorial 5, 


8 


This does a wildcard match of zero or more characters for 
when you forget the exact symbol name, or don’t need to 
type more for unique identification, “setl...” should have 
evaluated to ‘SetLight’ or ‘SETLIGHT’ for the Pascal 
sample. 


Set a One-Shot Breakpoint 


Control-Double Click (hold down the Control key TechRef 7.2.1 
and double click) on the address at the top left of the 
window (preceding ‘SETLIGHT' ). You just seta one-shot Tutorial 5, 8 
breakpoint and exited TMON. One-shot breakpoints are 
automatically removed after one use. 
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Trigger the Breakpoint 

Dismiss the “About Sample...” dialog if it is present TechRef 7.2.1 

Move the cursor over the Traffic window and click. Notice Tutorial 8 

how you hit the breakpoint and entered TMON. (Recording, 

Traps, and 

Using Control-Click instead of Control-Double Breakpoints) 
Click also sets a one-shot breakpoint, but does so 
without exiting TMON. Holding both the Option key and 
• the Control key down sets a regular breakpoint instead 
of a one-shot 

There are many useful keyboard shortcuts. They are all 
documented in the Tutorial and the Technical Reference, 
and can be overridden to your choice of keyboard 
commands. 

Window Configuration Options 

The unlabeled button (it looks like a normal Macintosh TechRef 4.2.6 

checkbox) in the top right comer of the Assembly window 

is the window preferences button. Select it and the Tutorial see 

configuration options will appear inside the window, along each window 

the top. Clicking the button a second time hides the description 

options. Not all window types have these buttons, and 

those that do (e.g. Dump, Assembly, ...) have their own 

unique selection of options. Click on the different options 

to see what effects they have. 

Create a Stack Crawl Window 

Press K-Option-C to create a Stack Crawl window. TechRef 7.1.4, 
After moving the resize box of this new window downward 7 • 1 • 3 

to enlarge the window, note that there are several entries. orial 5 

The number of entries vary depending on which version of (stack Lore . 
the Sample you look at Memory Windows) 

You know that you encountered a breakpoint at 
SETLIGHT. The Stack Crawl window indicates that the 
routine calling SETLIGHT is DoEvent, that the routine 
calling DoEvent is EventLoop, and the original caller is 
for the Pascal version called Sample. For the C version, it 
is called main, and the assembly version is unlabeled. 

Create Another Assembly Window 

Do a S-Control-Click on any of the addresses after TechRef 7.1.2 
the word “proc” in the Stack Crawl window, to open Tutor j_ al 5 g 
another assembly window open to the callee’s return 
address. 
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TechRef 5.6.13 

Tutorial 5 
(4NVOF?) 

Dynamic Evaluation Using the A Character 

Open up an Assembly window and press Tab. Now that 
the address field of the Assembly window is selected, type 
AO (Opt ion- J followed by the letter “o”), and press 
Return. “A” means dynamically evaluate the following 
expression. TMON Pro’s 0 variable is the expression. The 
O variable is a virtual register, set to the last Opt ion- 
click' d value. 

Call A the delay operator because it delays the evaluation 
of expressions. This means that an expression is never 
replaced by the value it is calculated to be at any moment 
but that value is nevertheless used. 

The 0 variable is a useful scratch-pad, as is TMON’s 
clipboard. Both hold information that can be subsequently 
entered by just typing one character (“o”) or 3€-v (to 
paste) respectively, instead of typing the entire value. 

Anchoring a Window to the Address Contained in the 
O Vanable 


TechRef 5.6.1 

Tutorial 5 
(Expressions) 


The O Variable is Doggone Handy! 

An Option-Click on the label “setlight” will cause the 
address of setlight to be stored in the TMON variable 


Now that AO is selected as the base address of the 
Assembly window, an Opt ion -Click over other 
addresses (in any TMON window) automatically 
disassembles code from the new address and displays it in 
the Assembly window. 


TechRef 5.6.13, 
5.6.1 

Tutorial 5 


You might sometimes find it convenient to keep an 
Assembly or Dump window opened to Ao. Important 
distinction: opening the window to just “o” and not “AO" 
would have caused the disassembly for the current value 
of o to occur once and not whenever the value of o 
changes; that is, the Assembly window would not be 
anchored to o. 


Any arbitrarily complex expression can be evaluated or 
dynamically evaluated. A Dump window can be opened to 
^expression, where expression is a handle dereferenced 
added to an offset and dereferenced again. If the block 
moves around in the heap, the window will always follow it. 
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CurApName as an Absolute Label 


Type 38-D, the number 910, and press Return to create 
a Dump window showing RAM beginning at the address 
of CurApName (aka the name of the current application). 
Sometimes the address of CurApName slips one’s mind, 
so TMON will automatically evaluate labels like 
CurApName for you. A dump can display memory 
locations, both as hex values of various sizes and as ASCII 
characters. 


TechRef 7.1.1 

Tutorial 5 (Dump 
Window) 


Dump Window Configuration 


If you have an ADB keyboard, type Control-w (not 36- 
w) and watch the window display as words. Type 
Control-L for long words, and Control-B for bytes. 
Open up the windows configuration section (click in the 
upper right corner). Notice you can also use the mouse to 
view the window by bytes, words, or longs. 


TechRef 7.1.1 

Tutorial 5 (Dump 
Window) 


Creating a Memory Window 


Type 36 -m, followed by typing CurApName, and then 
press Return to create a Memory window showing 
memory starting at address 910. A Memory window is an 
intelligent Dump window. It tries to display the contents of 
memory according to what is supposed to be there. For 
example, if you are examining a string, TMON will display 
it as a string. If you are looking at code, the memory 
window will disassemble the bytes you are examining. You 
can also edit the data in its native format. TMON uses a 
number of heuristics to display memory as intelligently as 
possible. You can always override these heuristics by 
asking TMON to display the contents of a memory 
window using a built-in or custom type definition. You can 
create your own custom types. 


TechRef 7.1.3 

Tutorial 5 
(Memory Window) 


Opening Multiple Windows of the Same Kind 


Type 3€-Shif t-M to create a new Memory window, The 
Shift key is useful for creating additional windows of the 
same kind. This allows you to view different sections of 
memory simultaneously. 


TechRef 


4.2.1 


Type Mouse, and then press Return. Notice that as you 
move the mouse, the values in this Memory window that 
contain the mouse coordinates are automatically updated. 
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Closing Windows 

Pressing the Option key while clicking the close box of a 
window will close all of the open TMON windows, which 
is exactly how the Finder works. Also like the Finder, 36- 
w closes the active window. To close all the TMON 
windows from the keyboard, type 36-Shift-w. 

Using a Command line Window 

Type 36-space to bring up TMON’s Command window 
(it should show up at the bottom of the screen). 
Commands are typed in in this window and invoked by 
pressing Return or Enter. 

With the copy of your original TMON disk still mounted, 
type open view "TMON:Samples:Sample .a" and 
press Return. This opens a view window to the source 
file for our sample program. This View window is read 
only, editing the file contents is not permitted. Files can 
also be opened by browsing directories rather than by 
necessarily typing path names. 

It is important to note that the above process for opening a 
View window to this file could have been done entirely 
with the mouse by clicking on the View menu item and 
navigating through the directories in a manner similar to 
the Standard File Package. The command line is useful for 
entering commands (including dcmds) when the 
keyboard is the most direct way. 

Find the identifier SETLIGHT in the View window you just 
created: Type 36-f, Then type set light, then type 
Return. Pressing Return will perform a find again 
function. 

3€-Control-Click on the label SETLIGHT in the 
source window creates an Assembly window just as if you 
typed 36-A setlight Return. Variations include 36- 
Option-Click to open a Dump window and 36- 
Shif t-Click to create a Memory window. 


TechRef 4.2.3 
Tutorial 4 


TechRef 7.3.1 
Tutorial 7 
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Multiple Commands in Command Windows 

Typing 36-SPACE to bring back a Command window. 
Type the following line in the window and press Return: 

Alert "hello" J Alert "there" 

The character between the two commands is a newline 
character. You can embed this character by pressing 
Shift-Return. Notice that after you hit return that both 
commands executed and brought up alert windows at the 
top of the screen. Simply clicking on the alerts or hitting a 
key will instantly dismiss the alerts. 

The AddMenu Command 

Typing 36-space to bring back a Command window. 
Type the following two lines in the Command window, 
ending each by pressing Return: 

AddMenu 100, "slow", "trace /leap,0" 
AddMenu 101, "crawl", "trace 0" 

The AddMenu command makes menu buttons. As shown, 
the first parameter is a refNum, which determines the 
button position and also provides a way of referencing the 
menu item (from DeleteMenu) without using the name 
string. The second parameter is the menu name, the third 
parameter is the string of zero or more commands that are 
executed when the menu item is invoked. These same 
commands can be entered directly from the Command 
window without creating menu items. See the manual for 
more information about AddMenu and DeleteMenu and 
how the refNum controls the menu item position and line 
separations. 


TechRef 7.3.1 
Tutorial 7 


TechRef 8.5.1 
Tutorial 7 
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Tracing Program Execution 

The Trace command is one of many TMON commands. TechRef 8.3.3, 

8 3 2 

The second trace bit, provided by the hardware of 68020 

CPUs and up, is used if the / leap option is on. This bit Tutorial 7 

controls whether a trace exception occurs on a change of 

flow (BRAs, JMPs, BSRs, ...) instead of on every 

individual instruction. This allows for a lower resolution of 

checking for a condition, but is noticeably faster. The 

argument, 0, could be any expression (e.g. 

AD0.W==$FE3C II memerror A ,W<>0), and which 
when it evaluates to true will cause the trace command to 
end and enter TMON. 

TMON evaluates each expression at each trace exception. 

A constant of zero will never evaluate to true, so invoking 
the slow and crawl menu items above will slow down the 
machine until the next time TMON is entered and exited. 

Try pulling down application menus with “crawl” invoked. 

If you have a 68020 or 68030, try “slow”. 

Note that under some circumstances when tracing, 
spurious trace exceptions can occur due to software which 
saves the status register (and thus the trace flags) and 
later restores it. When this happens, just ignore it and exit 
TMON. This is covered in detail in section 8.3.2 of the 
Technical Reference manual. 

Switching the Display Used by TMON Professional 


For those with multiple displays, try moving TMON to 
another screen by invoking the options command: 

options /screen=l 
options /screen=2 

Doing this often can be tedious; it is simple to make 
buttons called screenl and screen2 to do the job. Type the 
two AddMenu commands below into a Command window: 

AddMenu 200, "screenl", "options 
/screen=l" 

AddMenu 201, "screen2", "options 
/screen=2" 


TechRef 7.3.9, 
8.5.1 

Tutorial 5 
(Options 
Window), 7 
(Configuring 
Messages, etc. 
etc.) 
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Using a View Window to Inspect the TMON 
Professional Data Fork 


Let’s use a View window to inspect TMON’s data fork. 
First, select the View menu item to create a View window. 
This window should show an empty path expression in the 
top line, and identify each of the available volumes in your 
system. If you are already viewing a file in this view 
window, press Tab, then Delete, then Return. 


TechRef 2.2.10 
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Double-click on the volume that contains the System 
Folder. Scrolling the window as needed, Double-click on 
the System Folder. Scrolling as needed, Double-click on 
TMON Folder. Finally, Double-click on TMON to show 
the contents of the TMON data fork. 


This will show all the default menu and key commands. 
PUH-LEEEEEEEZE: we don’t recommend changing the 
TMON data fork, a place has been provided for your 
customization, the startup script, which is executed as well 
when TMON starts up. The startup script is kept in the 
TMON Settings document 

Some of the commands in the TMON data fork define new 
commands from old ones (Alias), menu items that 
invoke commands when selected (AddMenu), and 
keyboard key combinations that also invoke commands 
(AddKey). 

The Alias Command 


Alias is used to define new commands with holes in them 
to accommodate parameters. The Q (Option-Z) character 
indicates where a parameter is inserted. For example 


TechRef 8.5.1 


Alias scrn,"options /screen=£2" 

allows the shorter command scrn 2 instead of typing 

options /screen=2. 
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The Addkev Command 


Inspecting the AddKey commands, you will see in each 
invocation a cluster of upper and lower case letters. These 
indicate whether the keyboard modifier keys are used in a 
key equivalent. The modifier keys are known by the 
following single letters: 
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M Command (K) 
S Shift 
L Caps Lock 
0 Option 
C Control 
R Repeat 


If the letter is presented in upper case, then the modifier 
key is pressed, and not pressed if shown in lower case. For 
Example: 


MsLoCR 


means SS-Caps Lock-Control, and you held it down 
for a while. Addkey commands are used to define 
keyboard shortcuts for commands. Using DeleteKey 
and AddKey commands in the script of the TMON 
Settings file provides the flexibility for redefining and 
adding keyboard equivalents beyond those defined in the 
standard TMON startup script in the TMON data fork. 
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What’s in the Registers Window 

Open the Registers window by pressing S€-R. Drag the 
new window’s size box downward to see as much of the 
contents as possible. The top part of the Registers window 
contains the usual registers. Note the row of buttons on 
the top row labelled main, 1, 2, 3: main is the real thing; 
you can store copies of the real thing in 1 through 3, and 
move the copy back at your leisure. 

Copying from one register set to another is done by 
clicking on one of the buttons while ( don’t do this now!) 
holding the and/or Option keys down. It is also 
possible to copy/swap register sets using script 
commands. 

The next section down contains a text description of the 
last reason TMON was entered. 

If your machine contains a floating point unit (FPU), the 
next block down will show the contents of the floating 
point registers. 

Next down the block are the status and data registers of 
the memory management unit (PMMU). What is shown 
depends on what your Macintosh contains: if your 
Macintosh doesn’t have a PMMU, then TMON doesn’t 
show this information. 

Next-to-lastly, the contents of the exception frames are 
shown. These come in handy when returning from an 
exception on a 68020 or 68030-based Macintoshes 
because (under premeditated circumstances) those 
machines can be interrupted in the middle of an 
instruction and you need the data in the exception frames 
to return properly. Usually you don’t want or need such 
fine control over the handling of the processor exception 
and can ignore this information. 

Lastly, there are flags that you can play with, but don’t play 
with them right now. 


TechRef 7.1.7 
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Back to Traps 

Let’s do something else with a trap. Open the Traps 
window using either the standard menu item Traps or by 
typing 36-T. Also open the Record window (3€-Option- 
R). 

There are two entries, _WaitNextEvent and 
__GetNextEvent. ._EventAvail, already defined in 
the Traps window. Select using the cursor the “r” in the 
status flags group «rhSi» for _WaitNextEvent, type an 
upper-case “R”, and press Return; the flags should then 
be shown as «RhSi». This turns on the record operation 
for only the _WaitNextEvent trap. 

In the record window, select the window configuration box 
which is all the way to the right of the window, along the 
top. This should reveal among other things the buffer size 
value, normally set to zero. Select the number, set it to 
1000, and press Return. 

Press 36 -e and wait a few seconds, then manually re¬ 
enter TMON again. Check the record window for record 
of recent _WaitNextEvent trap calls. Set the buffer size 
back to zero, press Return, and note that the record 
window trap records vanish. 

Recording these traps should be turned back off now. 
Open the Traps window and change the case of the R flag 
back to lower-case by highlighting the R, typing a lower¬ 
case r, and pressing Return. 

Searching for a Trap Word 

Open a Search window by typing 36-Option-F. Type at 
the cursor _WaitNextEvent and press Return. The 
label will be turned into $A8 60: TMON commences to 
search for all instances in memory of $A860 and stuff the 
results in the Search window. 

Now open an Assembly window to Ao (the letter O, not 
zero), and Option-Click on the addresses found in the 
Search window to look at individual matches. Note that 
the 0 variable adopts the value of the address, and that the 
Assembly window follows because it is anchored to 0. 


TechRef 7.2.2 

Tutorial 8 
(Recording, 
Traps, and 
Breakpoints) 


TechRef 7.1.8 
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Displaying Identifiers 

Open an Identifiers window by typing 3§-l. Type 

s... 

(type Option-semicolon to get the ellipsis character) 
and press Return. This makes a list of known identifiers 
starting with an “s”. When listings get long like this, you 
can press 8£-periodto interrupt the search. Select the 
window configuration box for the Identifiers window and 
inspect the different options for selecting what kind of 
identifiers should be provided in the list. 

Typing 

/clear, /AO00=1,...dispatch 

and pressing Return creates a list of A000 traps ending 
with dispatch. You will probably find TMON’s wildcard 
pattern matching capability very powerful and use it 
frequently. 


TechRef 7.3.6 
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We begin our study with a cursory examination of TMON. In this chapter we 
discuss how TMON is activated, what TMON windows look like, and how TMON 
windows are manipulated. Mentioned also are keyboard and mouse interactions 
within TMON, what the TMON menu does, and how TMON window printing 
works. Finally, this chapter begins a discussion on debugging that is carried 
throughout the rest of the manual. It is in this context thatTMON’s usefulness and 
each of its capabilities are introduced. 


Starting TMON 

Once the Macintosh operating system has been started, and TMON has 
successfully gone through its own start up process, TMON windows can appear on 
screen either manually —by pressing a button or command key or automatically — 
by prearrangement. 


Manual Activation of TMON 


There are two manual ways to get TMON Professional’s attention. The first method 
requires pressing the Macintosh interrupt button of the programmer’s switch. On 
some (not all) Macintosh models, a two-button mechanism can be installed to help 
development. The first button is the interrupt button; the other is the reset button. 
Developers always install this programmer’s switch. 

Pressing the interrupt button when TMON is not installed will cause a nearly empty 
alert box to appear. If this happens, type G and press Return to continue. 

Pressing the reset button will cause the Macintosh to restart. (Developers are 
loathe to use the reset button, since pressing it always catches the operating system 
completely off guard, possibly resulting in a corrupt disk file system.) 
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Figure 4.2 Pressing the interrupt button when TMON isn’t installed 

The second method requires a Startup document called Programmer’s Key—to be 
installed in the system folder when the Macintosh is reset or “booted.” This Startup 
document expands the function of select keyboard keys when one or more modifier 
keys are pressed. When Programmer’s Key is active, holding the Option key 
down while you press the POWER key will cause TMON windows to appear on the 
screen. If it doesn’t invoke TMON, then try 3S-power. A copy of Programmer’s 
Key is provided on the TMON distribution disk (proper installation is described in 
Chapter 3). 

(<□ 

Programmer’s Key 


Figure 4.3 Programmer’s Key Icon in System Folder 

Automatic Activation of TMON 

Once in a while, something goes wrong. The machine often has no recourse but 
to display the Dire Straits alert. Most people don’t know what causes the alert to 
appear; they only know that the machine (or program) bombed. They often feel 
powerless to do anything about it except to phone customer support. 

Exercise Caution: TMON is Powerful 

When TMON is installed, it will appear in place of the normal Dire Straits alert. 
TMON should not be left active on a machine used by people unfamiliar with the 


TMON Professional Tutorial 


39 







Chapter 4. Elementary TMON 

product. Having a Dire Straits alert appear when something goes wrong is one 
thing, since both its message and its instructions are very simple. But, TMON is 
meant to be used by someone interested in debugging code. TMON Pro’s 
messages and windows are more complicated than the average end-user 
application. A user may become frustrated or angry that he/she can’t figure out 
what the really strange windows in his/her application want. 

A user may play with TMON until something bad happens. TMON has been given a 
great deal of power that is unavailable through most commercial applications. 
Remember Because TMON is built to annihilate defects, it does not provide users 
with many of the standard safety mechanisms. 


Why TMON Windows Look Different 

If you are like many developers, you’ve probably played with TMON a bit before 
reading this. You may have noticed that TMON windows are not like other normal 
Macintosh windows. Regular Macintosh windows, dialogs, and controls are driven 
by software provided by the Macintosh’s operating environment. Every application 
with rare exceptions uses this code. Reasons for not using the standard code are 
few: additional features, minor or major appearance modifications, or the need for a 
bug workaround (rare indeed these days). The reasons for using the provided code 
are strong: you don’t have to write your own, and standards are more easily 
maintained. 

Using standard Macintosh operating system code is avoided in TMON because this 
debugger must be independent from the software it’s debugging. When a regular 
Macintosh program has a problem that keeps it from running, TMON must keep 
working. It is easy for a buggy application to disrupt the Macintosh operating 
environment. Consequently, the TMON program contains (for example) its own 
window manager code. 

Some noticeable visual differences between TMON and regular Macintosh software 
are 1) TMON buttons appear visually only as text—without the graphic outline to 
make it look like a button, 2) TMON scroll bars lack a thumb but have move-by¬ 
page arrows, 3) TMON windows often show the contents of RAM with an 
enormous range of addresses that wrap around (when displaying a heap or data 
structure, an offset field provides direct access to any part of the displayable 
information). 

There are behavioral differences as well. Resizing or scrolling will not automatically 
bring the window to the front. Dragging will bring a window forward, unless the 
cursor is positioned in the scrollbar area between the scroll arrows, or at the top or 
bottom edges of the window. 
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Figure 4.4 Regular Macintosh and TMON Windows 

Manipulating TMON Windows 

TMON windows do not have a graphic equivalent of the Macintosh window title 
bar. Instead, they are moved up and down by selecting and dragging any part of a 
window. TMON windows can’t be moved from side to side. But, they can be sized 
vertically using the size control at the bottom right of each window. TMON 
windows can be sized horizontally by setting the Maximum width value in the 
Options Window. This sets the width of every TMON window being used. 
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The average TMON window has the following: 

• A top line that identifies the kind of window it is, accepting commands 
intended specifically for it 

• A Configuration Options button at the far top right of the window: selecting 
it makes the window’s configuration options appear above the informational 
portion of the window contents—just below the top line 

• Scrollbars with line and page scroll controls, as well as a size control 

• Hexadecimal address values that can be selectable or double-clicked on to 
create other windows 

TMON is Quiet 

Since any kind of sounds coming out of the Macintosh speaker requires the 
Macintosh operating system, TMON doesn’t use sound. When TMON requires 
your attention, it flashes the menu. 


TMON’s Menu 

The first thing that you will see when TMON makes a visual appearance is the 
window” menu along the top of the display, partially covered by a smaller alert 
window. The alert window contains a message describing the reason TMON kicked 
in. This alert will vanish when you press the mouse button or any keyboard key 
(this information is available in a Registers window). Pressing the mouse button 
over one of the selections in the menu will activate that item, even when the message 
window is visible. So, watch where the cursor is when you make the message 
window vanish. 

If you press the mouse button then later decide that you want to see the message, 
the message is displayed in the Registers window. 
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Figure 4.5 The TMON Menu 

The menu is where many, but not all, of the TMON windows can be opened. There 
are two classes of selectable standard menu items in the menu: 1) those that create 
a window and 2) those that execute a command. Clicking on a menu item will 
accordingly either display its window or execute its command. When TMON is 
accessible, the menu is always displayed—with one exception: all TMON windows 
are rendered invisible from the time immediately after the Show Screen item is 
selected until the next mouse click or key press. 
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What Are All the Windows For ? 

From the menu shown below, it looks as though there are nineteen different 
windows available in TMON. There are almost that many: for example, the Stack 
Crawl window is created using a Memory window. 

Each window used looks at a different aspect of the Macintosh software 
environment—from an assembly as well as a symbolic point of view. There is a 
good deal to look at 

It wasn’t necessary to be born a Macintosh guru to make good use of this 
debugging system. This Tutorial presents the easy subjects before the hard ones 
(those that require a passing knowledge of other parts of the system). These can be 
discussed without dragging in other parts of TMON. For example, the assembly 
chapter has been exiled toward the rear of this manual—despite the features 
discussed in the Asm chapter being the prime motive for buying the product 

Brief Descriptions of the Menu Items 

The following is a list which describes the action of each of the standard menu 
items (e.g., if the item opens a window) the window’s contents are briefly 
described. The operation of each window is introduced later within this Tutorial 
and described in detail within the Technical Reference. In the Tutorial, the 
information presented by each window is described first, with the window operation 
described second. This table is a summary intended mainly for developers who are 
familiar with the jargon. 

Window: Displays values in RAM as hexadecimal numbers and 
also in ASCII, with address names 
Window: Shows values in RAM as assembly instruction 
mnemonics (assembly code) and allows code to be assembled 
into memory 

Window: Shows RAM values automatically in the proper context: 
code is shown as code and data as data where appropriate. 
Manually use a type template of your choice for viewing memory 
Window: Shows RAM in addresses that are occupied by heap 
Individual heaps are identified by task 
Objects in heap are identified by address and type 
View custom heap zones 

Window: Shows resource file chains, and then files by resources 
Window: Shows contents of a directory, or the data fork of a file 
in ASCII form 

Window: Converts arbitrary expression to value or name 
Window: Lists TMON variables and their values 
Window: Lists names of labels, macros, traps, commands, 
dcmds, aliases, types,... 

Window: Shows registers and status words 
Window: Finds string in text file in view window 
Window: Searches memory for object (string, location,...) 
Window: Checks two ranges of memory for differences 
Window: Shows stack frames in RAM 
Window: Shows and manipulates execution stopping points 
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"Window: Sets what to do when AOOO traps occur; and controlling 
“Discipline” 

Window: Controls and displays the breakpoint and trap 
recording buffer 

Wmdow: Controls the printing options 
Window: TMON configuration options 
Return from exception (Return To Elvis) 

Exits TMON 

Exec 1 instruction, or an entire AOOO trap, JSR or BSR routine 
Executes one assembly instruction or AOOO trap routine 
Executes one assembly instruction 

Assume A7 points to a return address; execute until PC reaches 
the return address 

Assumes that the memory location indicated by A6+4 points to a 
return address and executes until PC reaches the return address. 
Terminates current application 
Backs off from the most recent editing change 
Copies highlighted text to the clipboard and remove original 
Copies highlighted text to the clipboard without removing 
original 

Pastes from clipboard to current selection 
Closes active TMON window 
Duplicates active TMON window 
Copies active window to disk file or RAM print buffer 
Snapshots active window to a capture window 
Makes TMON windows temporarily vanish so you can inspect all 
parts of the screen 

Customizing the Menu 

You aren’t stuck for all time with this menu. Once you get used to the way TMON 
does things, feel free to change it. This means that the menu you are using can 
contain different buttons than the standard one menu used throughout this 
Tutorial. 

If you do have a customized menu, you may want to create a new, standard TMON 
Settings document simply because this Tutorial is written assuming you are using 
the standard menu. This procedure is described in Chapter 2. 

Menu customization is detailed in Chapter 7, which includes discussions on 
commands and command scripts. 
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TMON On A Small Display 

In most of the screen snapshots used in this tutorial, a display greater than or equal 
to 640 by 480 pixels was used. This was done so that all of the information 
contained in a ‘ normal ’ TMON window is visible in the snapshots. 

Small displays, such as those of the original 128K Macintosh Computer, the 512K 
Macintosh, the Macintosh Plus, the Macintosh SE, and the Macintosh Classic 
contain 512 pixels across and 342 pixels vertically. The width is too short for many 
of the TMON windows to provide everything that a 640 pixel wide display can 
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provide. In instances where the differences may become confusing, the TMON 
Tutorial provides a screen snapshot of the window using a small display. 


Survey of Features 

Here is a quick romp across all the things that can be looked at, controlled, and 
changed with TMON. The six chapters that follow introduce and discuss these 
features in detail. 


Viewing and Editing Information 


Most developers want to look into memory and on disk with prying eyes. They want 
to inspect large areas of storage with interpretations of what the values mean, as 
provided by the debugging software. These values can be interpreted as data or as 
code, with the variety of ways this data can be interpreted being phenomenal. 
TMON provides easy-to-use defaults for displaying information, as well as simple 
ways for building templates that can be used to dramatically improve the readability 
of values that form complex records and macros, as well as simpler things that defy 
normal treatment. 

Known information such as the names of ROM-based trap routines, variables, and 
Macintosh resource types are known to TMON and are displayed when 
appropriate. TMON can display entire lists of these names in alphabetical order (via 
the Identifiers window, for example), after you type a string like “s... to get all the 
macros, types, traps, and commands starting with the letter s. 

This debugger employs variables to do its job. One window, Vars, shows all existing 
TMON variables and their current values, and permits you to edit them and create 
new ones. 

TMON can look inside the data fork of files on disk, using the View window. It does 
not look at the resource forks of disk files because other tools such as Resorcerer ™ 
and ResEdit™ already do this veiy well. TMON does provide ways to look at the list 
of resources that belong to open resource files, via the File command. 

Because TMON windows are verbose, some information that is normally displayed 
can be hidden when you don’t want to look at it. 

Assembly code can be inspected and edited using either an assembly window or a 
memory window. With the Assembly window, any memory location within its 
viewing range is assumed to be part of an assembly instruction, so it tries to display 
it as one. With the Memory window, the contents of memory addresses is checked 
first—in order to determine how the information should be displayed. Memory 
windows can show memory as though it were a simple Dump window, as an 
Assembly window, or as guided by a template definition. 

Number of a Different Radix 

One practical question that comes up early is “How do I type a decimal number into 
a window?” Normally, TMON displays and accepts hexadecimal numbers—if you 
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type in a number without a prefix character , the radix assumed is hexadecimal. 
Typing a number with a leading period is decimal; typing a number with a leading 
percent % is binary; and an octal is typed with a % (Option-Shift-E). 
Hexadecimal characters are displayed with the prefix $, so $ can also be typed in 
without a squawk from TMON. 

Types Indicate How to Show Data 

TMON distinguishes between showing information in different ways by using type 
definitions with a small but important twist. Where types are used in a high-level 
language like C or Pascal to control how the information within the typed variable is 
interpreted, TMON uses types to dictate how information should be displayed and 
keyed in. For example, the type for hexadecimal 32-bit integer is different than the 
type for a decimal 32-bit integer. 

Extending the Memory Window 

TMON permits you to define new type definitions based upon the existing primitive 
types provided with the debugger. This permits the definition of multi-field record 
types, which then can be used with the memory window to display a record in 
memory the way a true source-level debugger would. 

Breakpoints and Stepping 


A feature that modern debuggers typically provide software artisans is breakpoints. 
These are locations within the program code where the execution of the program 
should stop for the debugger to automatically take over so you can look at and play 
with the current state of the program. TMON is certainly no exception. One kind of 
TMON breakpoint is used to stop the entire program, with the option of not 
stopping interrupt-based code. When a breakpoint is hit, the TMON windows that 
you had created previously will display the current information on the heap, stack, 
memory, and register contents. 

Debuggers are used to watching code execute—sometimes at a much slower rate 
than is usual. In fact with TMON, you can watch assembly instructions execute one 
instruction at a time with a press of the mouse button for each instruction. This 
technique is called single stepping. 

Easily 99.999% of the time spent in debugging a program is not done by single 
stepping through program code. Since a 68000 processor running with a clock rate 
at around 8 MHz (the speed of the original Macintosh CPU) can execute several 
hundreds of thousands of instructions per second, single stepping an entire 
program would take millennia to finish. It is better to set breakpoints where you 
think something interesting will happen; then, let the program execute freely for 
several million instructions until it encounters a breakpoint. 

Set ’n Go and One Shots 

There are several ways to set breakpoints. TMON introduces the breakpoint set ’n 
go method, where you Control-double-click on an address to set a breakpoint 
there and run the program freely until something interesting happens or you reach 
that breakpoint. This is a handy way of stepping through a loop as if it were a single 
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instruction. Chapter 8 describes all of the operational details of breakpoints and 
trap watches, a variation of the breakpoint 

You can define a one-shot breakpoint by Control-clicking on an address to set 
the breakpoint. Unlike the set ’n go method, this leaves you in TMON so you can 
do other operations before exiting. When the breakpoint is encountered, TMON is 
brought up again, and the breakpoint is automatically removed. 

Commands and Expressions 

Some TMON menu items are connected to specific uses of TMON commands and 
are executed when the menu item is selected. Some of these commands are used 
for stepping through assembly code by the instruction, or by the routine. Menu 
items such as Exit allow code to run unfettered until a problem occurs, a 
breakpoint or trap is intercepted or you manually bring TMON back. Other menu 
items invoke clipboard operation commands like cut, copy, and. paste. 

The menu items provided by the default menu are actually specific versions of 
TMON commands. Commands can be typed in as well, through the numerous 
TMON windows. Each TMON window (e.g., the Assembly window) can directly 
accept typed commands that are related to its function. For instance, you can t type 
a trap command in a Breakpoint window. The command window is uniquely 
designed to accept any command in its most general form. 

A number of commands and forms of commands aren’t represented in the menu. 
TMON Pro’s command language is powerful and expressive enough to define 
scripts used for automating elaborate debugging tasks. 

A TMON expression is not a command, but an arithmetic or logical description that 
can be evaluated to a numeric or boolean result. Expressions are commonly used as 
parameters for commands. 

TMON expressions make TMON windows very powerful. It is possible to define a 
window’s behavior with an expression so that it watches memory, registers values, 
and reports whenever they change. Windows can be anchored to single registers 
and memory locations, with more elaborate expressions involving tick count, 
TMON variables...whatever. 

Real Time versus Debugger Time 

Although TMON is a native debugger, certain kinds of software are more difficult 
to watch. This is because TMON’s code is written to react with quickly incoming 
data. During this time, you may be unable to control the real data stream or even to 
temporarily turn it off. The mere act of watching the code work may slow the code 
sufficiently to cause other problems. Real-time code—which needs to keep up with 
incoming data without losing parts of it—is common. 

A simple and slow example of real-time code is the Macintosh human interface. If 
you press the mouse button, you expect the software to respond accordingly in a 
reasonable period of time. You do not expect the software to lose the mouse button 
press. A fast example is reading stock ticker data with the serial port: this data 
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comes in non-stop at 19,200 bits per second; you have no way to tell it to shut up for 
a while because this type of data feed ignores handshaking. 

Normal program defects in real-time software will still require normal debugging 
procedures (e.g., building a simulation of the incoming data with controls for speed 
ana content). This makes the problem-solving much easy. 

Sporadic problems, on the other hand, are tougher to solve. They need a TMON to 
diligently watch the execution of production code for the days or even weeks that 
will pass before the problem is manifested. Slowing the program down with 
debugging code could make the application too slow to handle normal data rates. 
Or, the problem may not appear at all. 

Normal TMON operation has little impact on execution time. There are a few 
features that must be used carefully to avoid real-time problems, but these are not a 

big concern in normal non real-time development 

Recommendations for Product Testing 


You will never really know what to expect from a program that goes out in the field, 
unless you first “shake it down” in its final commercially-available form. A program 
that is thoroughly tested while containing debug code is not sufficiently tested. You 
are never completely free from the possibility that debugging code could 
temporarily fix a problem that exists in software, rendering it undetectable. 

Adding More Stuff 

You can add new types to TMON to make memory windows more powerful. You 
can write elaborate TMON command scripts and store them on disk for later use. 
You can add, delete, and modify menu items from the menu by editing the user- 
configurable TMON startup script in the TMON Settings file. You could change the 
standard TMON startup script in the TMON data fork, but this is highly 
unrecommended. (Shame on you for even thinking about it!) You can add, delete, 
or modify any TMON command-activating keyboard key/mouse click sequence. It 
is likewise possible to add and delete error messages. 

You can create new commands by defining MacsBug-compatible DCMDs 
(resources that contain code to handle a debugger command). Finally, the really 
savvy developer can create a TMON user area—extensions to the TMON debugger 
by adding code and other resources. 
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An Elementary Summary 

Entering TMON manually is simple. So is adjusting the display of the windows on 
the screen (once you know the secrets). When TMON automatically appears, it 
means that your application is “on hold” and that a breakpoint, trap intercept or 
trace condition was encountered—or something bad happened. In any case, TMON 
displays a message describing the reason. The menu can be used to activate a 
reasonably long list of features. Even though TMON is an assembly level 
debugger, it is useful to high-level developers. TMON is a powerful tool that can 
address a problems at the assembly-level and above—including real time code 
with sporadic bugs. TMON is designed to watch Macintosh applications, utilitiess, 
and operating system code, and is written to be as independent from the Ob as is 
possible. TMON is configurable and extensible at many levels. 
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The several different “building blocks” used in software are introduced in this 
chapter. Each has a demonstration of looking at and changing them with the 
appropriate TMON facility. These building blocks are anything and everything that 
reside in random-access memory: code, pointers, handles, resources, and data. 

Because a iscussion of memory objects doesn’t make any sense without them, also 
mentioned at length are registers, heaps and stacks, and the TMON windows’used 
to manipulate them. 

This chapter covers the following windows: Dump, elementary Memory, 
Registers, Heap, and stack Crawl. It also introduces the command 
expressions. 

Each of the TMON windows described in this chapter can be controlled by 
employing specified key press combinations (such as Tab for moving the edit 
cursor home), mouse selections dike selecting checkboxes), and by typing out the 
commands in scripts or in a Command window. Coverage of command scripts and 
the full command language starts in Chapter 7 of the Tutorial and continues from 
there. 


Data 


Data exists in a multitude of forms and can take up any amount of space: one bit, 
64K bytes or even more memory for a single structure. 

Starting small, there are many ways to interpret the contents of the humble byte (8 
bits) of data. Here are three: 

1. As an unsigned integer (where values can range from 0 to 255 decimal) 

2. As a character (‘A’, ‘Z’, etc.) 

3. As a signed integer (legitimate values go from -128 to 127) (a.k.a. the 
infamous SignedByte type) 


There are as many ways to display one byte of data. Where it is common for 
source-level debuggers to display program variables as their declared type would 
indicate (integer, sub-range, and floating point) it is rare for assembly-level 
debuggers to go beyond the essentials of signed and unsigned bytes, words, and 
longs. Traditionally, assembly-level debuggers have been limited in their approach 
of displaying data. 

TMON isn’t just an assembly-level debugger, it is a powerful symbolic debugger. 
Although, it is not designed to completely replace the source-level debugger 
provided with the development language you may be using. In this kind of problem 
solving, you are more likely to be interested with addresses (e.g., the contents of 
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pointers and handles). TMON’s prevalent use of hexadecimal representation in 
most of the standard TMON windows, fits well with this intent 

TMON displays processor-supported data types as intelligently as possible. To 
illustrate: IEEE standard floating point values are shown in readable form, with 
integer values shown from a selection of bases (like octal and decimal). If provided 
with enough context, TMON nearly automatically shows data in a form true to the 
content Often however, the executable program is provided without any symbol 
table information, so TMON has to do without. It is then up to you to figure out 
what kind of data is at memory addresses of interest and have TMON display them 
appropriately. 

A high-level language like Pascal will permit you to define a type to contain a 
defined range of integer values, e.g. all the integer values from -6 to 20 decimal. 
Exactly how a variable of this type is implemented depends upon the language and 
the compiler. For example, one compiler will use the smallest integer that can 
handle the entire legitimate range of values. Few commercial compilers 
automatically go to the trouble of optimizing sub-ranges down to the bit level (the 
range of Sunday..Saturday could be represented in just 3 bits); compiler users 
would rather that you not go to the trouble. 

What’s the point? Most compilers are written to store data so that the processor can 
work efficiently. On the Macintosh, data is normally stored as allocated memory in 
multiples of bytes. You can expect data items to “line up” when you look at it with 
TMON. TMON helps a bit in recognizing what’s there by displaying symbol and 
address labels next to the address and actual data. 

It is important to understand that data items that are easily distinguished at a high- 
level look awfully alike at the assembly level. The easiest to recognize is character 
data. So, TMON’s Dump window is set up to directly show ASCII character data 
without fanfare. Character data is unusual because it is often easy to read without 
the need of knowing the data’s machine context. Other types of data may be 
recognized by their hexadecimal patterns, but they aren’t as readily understood 
when represented as a hexadecimal value or a character string. TMON naturally 
gravitates toward showing byte-oriented data in hexadecimal and character form. 

Packed information is where individual values are squeezed together in defiance of 
normal byte or word boundaries. This is done to save memory or disk space. 
Packed data is harder to manipulate than unpacked data. 


Labels, Names, Constants, Symbols 

To tell the difference between one cluster of hexadecimal values and another, all 
software development kits support labels —human-readable names or type 
identifiers. Current TMON label support is improved over the previous version of 
TMON: it knows quite a few absolute labels and deals with a wider variety of 
commonly used types of labels. 

TMON labels are names represented by ASCII characters. These can be anywhere 
in memory and can be attached to anything to help identify what something in 
memory is or does. This debugger comes out of the box knowing a large number of 
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the Apple-defined labels for the system code in the ROMs (e.g., all the names of 
the Macintosh Quickdraw calls). 

When you compile and link an application, usually you can provide TMON with all 
of the labels within your program. This makes it easier to understand what you are 
debugging. 

Depending on what they’re attached to, labels are called different things. A label 
attached to an assembly instruction without more information can be simply called 
a label. A label attached to a procedure or function can be a name. A label 
associated with an unchanging value can be the name of a constant. 

There are also differences in labels by how they are implemented and by what they 
are representing. 

The different types of labels supported by TMON are described generally here. 
More details are provided where appropriate in the rest of the Tutorial, as well as in 
Section 5.4 of the Technical Reference. 

Absolute labels are used to identify fixed memory addresses such as system global 
addresses. These absolute labels are associated with an address. But the label 
itself—a string of characters and the address information—is not kept in memory 
near the location it identifies. It is located elsewhere in the system. Absolute labels 
are not required for the system to work; they’re provided merely to make a 
developer’s life easier. Programs that need this information (like TMON) can be 
supplied with them. 

Embedded labels are used to identify code, and are intended to be used with 
debugging systems. The label itself is located near the code it represents. So 
wherever the code is—for instance, in memory or in a file—the label will be nearby. 
An embedded label is usually placed at the end of the function’s compiled code it 
identifies. Unfortunately, there are a number of embedded label formats in common 
use; fortunately, TMON supports all of them. Following are examples of embedded 
labels and their differences: the Object Pascal label—which is twice as long as the 
classic embedded label; the C++ label—which is “mangled”; as well as other 
common formats. 

Register-relative labels are used to identify memory locations, with an offset and a 
base provided by the contents of a register. A register can contain any address, so 
register-relative labels are not absolute addresses. 

Resource-relative labels identify locations within a resource. Because resources can 
be moved to different locations in memory, the only thing that’s certain is the offset 
of the location within the resource from the beginning of the resource. 

Computed labels are provided by TMON as a convenience. They are created 
automatically using an application’s “A5-based jump table,” so that it is easier for 
you to follow code using jump tables. 

rhere are a small variety of pseudo labels that provide one form or another of 
identification—including type identification rather than providing a unique identify. 
For example, common system data structures have pseudo labels. 
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Turning Labels On and Off 

When you get a chance to look, determine which kinds of labels should be visible in 
TMON windows by selecting individual checkboxes in the Options window 
(introduced at the end of this chapter). 

Dump Window Basics 

The first button in the standard TMON menu is Dump ( §€d ). Selecting it with the 
mouse or pressing the command (also known as §§) and the D keys together will 
activate a Dump window by creating one if one doesn’t exist. If a Dump window 
does exist, it is brought to the front and no new Dump window is made. Holding 
both the Shift and K keys down when pressing D will create a new Dump window 
every time, until memory is filled with them. Performing this procedure may take 
some time. 

TMON windows often have many controls that you can adjust with the mouse. It is 
too early to bombard you with details, but keep in mind that many of the fields and 
controls can be changed by either using the mouse, a short keyboard key sequence 
or a text command. 

The Dump window shows what is in each byte of memory by using a simple 
numeric interpretation of each value. A byte number can range from 0 to 255 in 
decimal (base 10). The Dump window displays, by default, each byte as a 
hexadecimal (base 16) number and as the ASCII standard text character assigned 
to the number. 

Also automatically shown are any known operating system address labels 
associated with each displayed memory location. In addition, any program—related 
labels known to TMON are displayed. Labels are nominally shown in the form 


Name+Offset 

where the optional offset field is calculated by TMON for the first byte in the line, 
from the first address of Name. 
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Registers and Variables Containing Values Equal To This Address Hidden Options Box 
GoAwa) ox / Address Expression Memory Contents as Hexidecimal Bytes 
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Memory Contei^ as ASCII 


Figure 5.1 Dump window displaying bytes from location $00000000 

The top line of the Dump window consists of a GoAway box on the left, the window 
caption (“Dump f rom”) , the address of the first byte of data shown in the window 
and the Window preferences box all the way to the right. Selecting the GoAway box 
removes the window. The Window preferences box will be described shortly. 

Setting and Using Dump Window Addresses 

You can specify a base address for the Dump window in the form of any legal 
TMON expression. A simple example of this is creating a new Dump window (this 
way the Dump window address is automatically highlighted) and type any arbitrary 
hexadecimal number, like 0 or FFOO. You could also type a label known to TMON 
like ApplLimit. 

Expressions can be wonderfully complicated. Sections covering them in detail are 
found 1) after the discussion on registers in this chapter, 2) in this Tutorial’s 
Chapter 7 discussion of commands, and 3) in the Technical Reference. 

A Handy Address for Playing 

Sometimes you may want to assemble a small piece of code somewhere, point an 
address register off to a free area to store results or need a piece of memory for 
another purpose. Wouldn’t it be nice if there were a free area of memory 
guaranteed to be available for whatever you had in mind? There is! 

TMON sets aside a 512 byte area named PlayMem. For example, you can specify 
PlayMem as an address for a Dump or Assembly window and modify the memory 
however you wish. The size of this area can also be changed. (See Section 6.1 of the 
Technical Reference for more information.) 

What Can Be Done With Point ’n Click 

Simply by clicking on a value displayed in any TMON window, will make TMON do 
something including Dump. This feature alone is worth the price of admission. 
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With no modifier keys pressed, TMON behaves as any other Macintosh program, 
clicking in editable areas makes it possible to edit those values. Clicking once in the 
Dump window places a blinking insertion point in the hexadecimal data part on that 
portion of the line nearest the cursor. But clicking in the ASCII area creates a solid 
ASCII edit cursor which permits you to change information usmg ASCII characters. 


Click to Create Something 

With one or more of the modifier keys held down, TMON will do different useful 
things at one or two mouse clicks: open new windows, set and clear breakpoints, 
set monitor variables or step through program execution. All of these actions use 
the value selected by the click as the pertinent address for the command. Not 
having to type value expressions all the time seems to magically accelerate the 
debugging process. 

Here’s how to create some windows: 

—To create a Memory window, hold the key down and click on a value. The 
selected value will be its base address. 

—To create a Dump window, hold both the key and Option key down and 
click on a value. The value will be its base. 

—To create an Assembly window, hold both the $6 key and Control key down and 
click on a number. 


Key Equivalents for Setting Breakpoints 

These modifier key-mouse click combinations work with breakpoints. These are 
mentioned again when breakpoints are discussed; for now, just note that they exist 


without trying them out: 
Control-Option Click 

Control-Option Double Click 

Control-Click 
Control-Double Click 

Control-Shift-Click 

Control-Option-Shift-Click 


Sets a breakpoint at the address indicated 
by the selected value. 

Sets a breakpoint at the indicated address 
with TMON exiting immediately. 

Sets a one-time breakpoint. 

Sets the one-time breakpoint with TMON 
immediately exiting. 

Clears a breakpoint. 

Clears a breakpoint. 


Key Equivalents for TMON Variables O and N 

There are also modifier key-mouse click combinations for setting the O and N 
monitor variables, used by some parts of TMON to store values (e.g., the N monitor 
variable is used by the number window). Monitor variables are covered at length 
later, but here are the key-click combinations used to set some of them (there are 
others): 
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Option-Click 
Option-Double Click 


Option-Shift-Click 
Option-Shift-Double Click 


Sets an O variable. 

Sets an 0 variable and opens a new number 
window with the selected value displayed as 
numbers in hexadecimal, decimal, ASCII 
(with Macintosh extensions), and as a label 
known to be associated with the address. 
Sets an N variable. 

Sets an N variable and opens a new number 
window. 


If you play with these (they’re safe), note that an N or an 0 appears in a TMON 
window to the immediate right of the address column-in the line whose address 
was selected as a value. 

ASCII Character Editing 

If the mouse is used to select a character in the ASCII part of the Dump window 
A h fprf n , A f SC . n character will be block-highlighted —a good indication that editing 
ASCII data is a little different. The editor for the ASCII data does not permit 
insertion since ASCII Data is considered to be position-sensitive in TMON. A 
lghlighted character is replaced by typing in another character, with the 
highlighted block automatically moving to the next character. 

Double-clicking on a line highlights the nearest hexadecimal value; however 

fw ble -? llC S ng . 0V 5 th r ^ SCH dispIay area has the same effect as clicking once 
2 2 na ^’ tnp M ~-choking highlights an entire line of hexadecimal data. 

lgh lghting is useful because TMON supports the standard clipboard commands- 
Cut, Copy Pa ste , and Undo, and the clipboard operations work with highlighted 
text. Note that you are allowed to highlight only a single line of hex values at a time. 

Pressingthe esc (escape) key cancels any changes. It also re-highlights from the 
start ox tne xield. 


Entering Information 


Pressing either Return or Enter indicates that TMON should 
was typed or pasted into a window. 


accept whatever 


The key sequence Shift-Return can be used instead of Return 
enter multiple commands onto a command line. 


or Enter to 


The Isabel and Offset Column 

1 2i° ^^ iis P ! f y s a Jj the address label information it knows (including the contents 
of the Macintosh ROMs and the operating environment it comes with). The size of 
blocks in memory js shown by the label and an offset value from the base address 
on each line that is occupied by a block. The names of some blocks are quite 
elaborate, e.g. DCE $FFFB ($0004) and << Block Header >>. 


When the label takes the form: 
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$Number A +Offset 

The ‘ A ’ indicates that a pointer is located at the address. For all intents and 
purposes, the pointer address is the label for the structure. 


□ Dump 
I000139A0: 


000139C0: 

[000139D0: 

000139E0: 

000139F0: 


00013A10: 

00013A20: 

00013A30: 


©0013A50: 

00013A60: 

00013A70; 


00013090: 


00013AB0: 

00013AC0! 

00013AD0I 

00013AE0: 

I00013AF0: 


00813B10: 


from *000139A0 

*0000B1C0-+*00FC: 
*00008 1 C8~«-*010C: 
«Block Header»+*8004: 
$00001EC4^*000C: 
*00081EC4-+*001C: 
*0000lEC4-^-*002C 
*00001EC4^*003C: 
*00001 £C4'-+*004C: 
*00013A20 
«81ock Header* 

DSAlertTab+*0008: 
DSAleriTab+*0818: 
OSAlertTab+*0028: 
DSAlertTab+*0038 
DSAlertTab+*0048 
DSAlert T afcr**0058 
DSAlertTab+$0068: 
OSAlertTab+*0078: 
DSAlertTab+*0088: 
DSA1ert Tab+*8098 
DSAlertTab+*00A8: 
DSAlertTab+*00B8: 
DSAlertTab+*00C8: 
DSA1ert Tab+*00D8 
DSAlertTab+*00E8: 
DSA1ert Tab+*00F81 


48 E7 FF EE 
51 E7 4A IF 
00 00 00 C4 
28 6E 00 08 
D6 FC FF FC 
FF FC 59 AE 
70 00 26 80 
18 00 FF F4 
00 00 00 00 
82 00 06 00 
00 80 00 24 
00 25 00 60 
00 00 80 00 
00 46 00 1C 
00 2A 80 8A 
00 0A 00 36 
00 2F 00 00 
00 00 00 27 
80 27 00 00 
72 72 79 2C 
72 6F 72 20 
00 1C 00 56 
20 74 68 65 
00 1C 00 IE 
65 72 74 20 
06 32 00 64 


4C DF 77 FF 
4E 75 A0 24 
07 D0 00 01 
20 2E 80 0C 
28 78 01 18 
FF FC 20 6E 
27 38 01 18 
4E 5£ 4E 75 
00 00 00 08 
00 00 00 3C 
08 5E 08 48 
00 00 00 IF 
80 29 00 0A 
00 0A 00 32 
00 2C 00 00 
60 00 00 00 
00 27 04 4A 
00 00 00 47 
00 47 00 32 
20 61 20 73 
6F 63 63 75 
00 82 43 61 
20 66 69 6E 
00 4B 50 6C 
74 68 65 20 
00 6E 59 6F 


26 78 03 94 
4E 75 4A 78 
4E 56 FF FC 
00 8C 2D 40 
21 4B 


26 53 4E 03 
80 00 00 5C 
48 E7 00 18 
FF FC 26 40 
60 0E 06 FC 


FF FC 20 88 B9 CB 60 EE 


A3 C0 00 
40 00 00 18 
00 00 00 00 
08 27 7F FF 
08 IE 00 8A 
00 0A 00 20 
00 43 00 00 
00 00 00 24 
00 27 00 61 
00 00 00 00 
00 4A 00 63 
00 62 00 0A 
00 24 00 64 
79 73 74 65 
72 72 65 64 
6E 27 74 20 

64 65 72 21 

65 61 73 65 
64 69 73 6B 
75 20 60 61 


4C EE 
00 00 IE 00 
00 08 00 08 
00 0A 00 32 
00 2E 00 00 
00 00 00 25 
00 24 00 00 
00 5F 00 48 
00 48 FF F5 
00 1A 00 0A 
00 0A 00 4B 
00 4C 00 00 
00 6E 53 6F 
60 28 65 72 
2E 00 00 43 
6C 6F 61 64 
00 00 00 2E 
20 69 6E 73 
3A 00 00 2C 
79 20 6E 6F 
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_<. * . 

,j4 

..5...C 


'. J. J.c.. .1 

,6.t>. . .L. 

. . ,6.2.*.<5.nSo 
rry, a system er 
ror occurred...C 
.♦.U.CCan't load 
the finder!. 
.♦.♦.KPlease 

ert the disk: _ 

■ 2.d.nVou may nojCjbl 


Figure 5.2 Example of labelled block in Dump window 

Often, the first byte of a structure doesn’t start conveniently at the leftmost byte of a 
row The first mention of a structure in the label column will be accompanied by an 
offset. To find the first byte of the structure, count backwards as many bytes as 
indicated by the offset. 


□ Dump from *800060F0 


08000110: 

00000120: 

00000138 : 


‘MonkeyLives’ : FF FF 00 40 

‘StkLowPt’ : 00 6D 18 A4 

‘HacJmp’ : 70 6F F5 AA 

*ApplLimit’ : 00 60 12 AC 

4 PolIProc’+*0002: 



SA!,e«!.UHm..oA 4 ! 
. . .M.M.e.A. o r. 
.m. $.«*'" .ee 
poi’* 


.01 _ 

.0..BA. 


'PollProc'+$0000 


Figure 5.3 Example of counting backwards to find the beginning of a structure 

4NVOF? 

When you first enter TMON, each of the N, O, etc., variables is initially set to 
00000000. (This remains true until you reset the variables.) These variables 
appear in a left-justified bunch within the label column of a TMON window 
displaying the contents of memory address 00000000 (e.g., the “4” stands for the 
A4 register). 

Hexadecimal Data 

Hexadecimal data is easily highlighted with the mouse, edited with the keyboard, 
and changed with the clipboard—at a maximum of one line of hex data at a time. 

One line can be up to 400 characters in length. 

Re-configuring the Hexadecimal Data Column 

By default, the data shown in hexadecimal form is displayed as bytes. It is easy to 
reconfigure the Dump, Memory, and Stack Crawl windows to show the 
hexadecimal values in words (16-bits) or longs (32-bits). Selecting the preferences 
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box at the far right of any TMON window will cause the window-related 
preferences to become visible. Then, you can select one of the byte, word, or 
long radio buttons among the normally hidden window preferences. Pressing 
Control-B, Control-W, or Control-L also does this. 

ASCII Data 

As mentioned earlier, the text data editor does permit changing characters, but 
does not permit character insertion—where all characters following the insertion 
point are pushed back into higher RAM addresses by typed-in characters Typing 
in a replacement for the highlighted character causes the “cursor block” to move to 

Ao^f« t , ch ^ racter ’ as tf™ 0N were emulating the way a cursor works on an old 
ASCII “dumb terminal.” 

Dump Window Preferences 

The window preferences box was briefly introduced to discuss the hexadecimal 
value display switch between byte, word, and long. Now, we’ll discuss other 
normally hidden preferences. 


Memory Address Protection 
Data as Hex Group Size 



Data as ASCII Extended ASCII 
Character Set Toggle 

24 or 32 Bit Selector 


Filled: Current Selections 
are the Default 


□ Dump V or *00000000 

??£ res 3 ,ffl iC * ! *O0ir«ct Orton it 0 . 7 ® User OCuslon Dsz'bil 
®Byte Outrd OLong DRestrictld ASCII SAlign 
Capture * 00000000 .. * 000000 “ 

Print <00000000..$00000050 



Set Oefaultl 


8A..Go**.A~..A“. 

. .~+.A-'8.efl! .601 
6ft! . .COD.CG.Gft! .i 

eft!.eft!.eft!.eft!. 
eft!.eft!.eft!.eft!. 
eft! .eft!.eft!.eft!.I 


Print (DisV) Buffer Capture (Screen) Buffer ' Hex Data Address Alignment 
Address Range Address Range (Align White Space to Multiples of 4 or 16 Bytes) 


Figure 5.4 Dump Window Preferences 
Your Choice of Address Spaces 

The first line contains radio button selections for physical, direct, monitor, user and 
custom memory address spaces. Generally, address spaces are ways of viewing 
memory. It is possible to see how an application views memory, how the PMMU 
views memory, and even how TMON views memory. 

Although TMON offers some amount of protection, it should be noted that the 
address spaces themselves are not protection methods. Some address spaces 
^ r °^jj SenS ^ Ve memory addresses from being modified by remapping portions of 
the address space. Addresses that are mapped to I/O devices can also be shielded 
Some memory addresses may be technically harmless to access under normal 
circumstances. Yet, accessing them under TMON triggers a TMON bus error 
message. 

Th e user method is selected by default; that is, TMON shows the current state of an 
application when TMON appears on the screen. You can determine which 
application it is by looking at the name (stored as a string at location CurApName in 
low memory). In the user address space, CPU registers, low memory globals, and 
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stack all are within the context of an application program’s run-time environment, 
not TMON’s. The alternative is to select the monitor .address space that belongs to 
TMON, so you can look at TMON’s own runtime environment 

The direct method is a direct mapping of the CPU’s logical address space, which 
includes NuBus slot addresses. No protection is provided here. 

The custom method is a copy of the user address space and what is in it. But you 
can experiment by changing the copy—-without affecting the original by using the 
Map command. 

The physical address space appears if you are using a 68020-based Macintosh 
equipped with a 68851 memory management unit, or a Macintosh with a 68030. 
This address space permits the exploration of all physical memory by bypassing the 
logical to physical mapping provided by the Macintosh’s memory management 
hardware. Physical address space can be viewed only in 32-bit mode. A brief 
explanation of 24- and 32-bit mode follows. 

Selecting 24 or 32-bit Mode 

For those machines which support both 24 and 32-bit addressing modes, TMON 
provides a checkbox for your preference. This checkbox appears on the same line 
as the memory addressing preferences. This option allows selection similar to the 
action of the SwapMMUMode trap. 

Remember that the 68000-based machines support 24-bit addresses only. 

The keyboard command Control-Option-3 toggles memory viewing between 
24 and 32—bit address modes. 

In this context, the MMU mode refers only to the view TMON has of data. It does 
not change the state of the application’s environment between 24 and 32—bit 
addressing modes. (You will see later that TMON is capable of this as well.) 

Memory Space Keyboard Command Equivalents 

The following are the key press combinations that can be used to select an address 
space). 

Control-Option-P selects physical space. 

Control-Option-D selects direct space. 

Control-Option-M selects monitor space. 

Control-Option-U selects user space. 

Control-Option-C selects custom space. 

Control-Option-S toggles 32-bit mode. 

Standard and Extended ASCII Data 

There are two ways of looking at the ASCII column: 1) standard and 2) extended. 
Selecting the Standard ASCII checkbox means that you only want to see 
normally visible ASCII characters with the Macintosh-defined ones displayed as 
dots. The standard ASCII set is pretty much what is shown on the keyboard keys 
(excluding the function keys) including upper and lowercase alphabetic characters. 
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The TMON default is to show the extended character representations. The 
Standard ascii checkbox does not affect the contents of memory. 

Aligning Hexadecimal Data 

Normally a Dump window is based on an address at a longword boundary (a 
multiple of four). At times when this is not true, TMON provides a visual reminder 
to indicate hexadecimal data. This reminder may be displayed in two ways Select 
your preference by using the A1 i gn checkbox. 

By default, the Dump window shows hexadecimal data in groups that are address- 
sensitive. To illustrate: in byte mode, each hex byte is grouped with three other hex 
bytes with groups separated by a wide space. A wider space shows 16-byte 
alignment. Therefore, the first group in the window always contains four bytes. 

ith Align turned on, groups are aligned in four-byte multiples starting from 
memory address $00000000. 

With the base address of the Dump window at $00000001, for example, the first 
group is shown as three bytes and not four. The Align checkbox does not affect 
the contents of memory, and only align affects how the byte-oriented mode 
displays the information (word and long are left alone). 


□ Ounp frort $00000307 « 

Address space: OPhysical ®Oir@d 
®Byte OWord OLong OStandard i 
Capture $00000307..$00000337 
Print $00000907..$00000337 


Alignment of Byte Data Columns 


Extends 


Orton it or Outer O Cut ten Q32 bit 
SCII ®Align 


00000907: 


00000927: 

00000937: 


‘CurrentA5’+$0003; 84 00 60 92 84 FF FF FF FF 

*CurApNane’+$0007: 20 20 20 20 20 20 20 20 20 

'CurApHane'+$0017: 0C FF FF FF FF 00 00 00 04 

CurPageOption * +$0001: 00 FF FF FF FF FF FF FF FF 


06 46 69 6E 
00 00 00 20 
00 65 66 50 
FF FF FF FF 



fa 

□ Set Oefault 


64 65 72 Pf. nl¥.Finder] 

20 00 .iefP 

FF FF FF . 


Figure 5.5 Byte Alignment and Standard versus Extended ASCII 

Capturing and Printing Window Contents 

Capturing the contents of a window is excellent for taking a snapshot of memory or 
a data structure for later comparison. 

TMON provides an automatic way to reserve memory for a capture and a print 
buffer . Once enabled, the capture and print buffers are used by placing the insertion 
point anywhere on the print or capture buffer line in a window’s preferences 
section, then pressing Return. 

Printing is enabled by clicking on the Printing button in the TMON control 
window (or typing 36 -P). This opens the Printing window. Select one or both of the 
destination checkboxes for printing: 1) either create or append to a disk file, 2) 
store in the bottom of the Printing window. The type of the saved disk file is the 
same as an MPW shell document. The capture buffer is used to always display the 
captured contents in a new TMON view—like window. 

The address range displayed on both the capture and printing lines in the Dump 
window is the argument required to print/capture the visible portion of the window. 
To practice, resize the Dump window and watch the print/capture ranges change to 
handle the amount of data. These numbers are normally maintained automatically 
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by TMON, so you don’t need to play with them now, but you may sometime need to 
specify a print or capture range. 

More details (e.g. keyboard commands and tab compression) are discussed in the 
section covering Capturing and Printing. For example, an alternative way to 
perform a print or capture is to issue a TMON Print or Capture command from 
a Command window. 

Scrolling the Dump Window with Keyboard Commands 

Scro lling the Dump window by pressing keyboard keys is simple: 

Control —> Advances the Dump window by one, two, or four bytes, depending 
on whether you’ve selected byte, word, or long display mode, 
respectively. 

Cont rol— <— Backs the Dump window by one, two, or four bytes. 

Introducing the Dump Command 

Using a Command window (make one by pressing §€- space), you can type in the 
following script command to create a new Dump window that starts at location 
$ 100000 : 

New Dump $100000 

This always make a new Dump window. Selecting a menu item in the TMON menu 
actually causes a script command to be executed. Script commands can be esoteric, 
which is why they’re introduced here and not discussed in detail until the simpler 
features of TMON are described. Because this Tutorial emphasizes interactive 
TMON use, the use of script commands is covered in greater detail in the Technical 
Reference. 

About Window Prefixes 

When typing the Dump window command, the prefix New must be typed in before 
the keyword Dump to create a new window, as in this example: 

New Dump $100000 

Another prefix, Open, is implied when selecting the Dump menu item. When 
selecting Open, you are actually executing: 

Open Dump 

Open means to create a Dump window if one doesn’t exist or the shift key is down; 
otherwise, use the next one in the window list. New always means to create a new 
window. 

Default means set the preference defaults for this type of window based on the 
command arguments; First and Last refer to the first and last window in the 
window list, respectively. 
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These are the non-printing prefixes: Default, New, First, Last, and Open. 
These prefixes can be used with the Dump command or any other commands used 
to create or work with windows. 

These are the printing prefixes: Print and Capture. Print takes the results of a 
command and dumps it to a disk file or to a print buffer in memory. Capture takes 
the results of a command and dumps it to a capture window. (Both of these prefixes 
are described in detail in Chapter 5.) 

Other Useful Commands You Should Know 

Using a Command window, the following commands may come in handy: 

Reboot using shutdown manager 
Flush and unmount all disk 
volumes and then reset machine 
Reset machine 

Close current application files and 
exit application 

iter in this Tutorial, as well as in the Technical 
Reference. They are mentioned here, because its always nice to be able to escape- 
just in case you accidentally do something that you can’t recover from easily. 

Viewing Memory from a Better Vantage 

Although Dump windows are great for editing simple information—streams of 
bytes, words, longs, and ASCII information—a good deal of important information 
is moved about in the form of typed records. This section introduces TMON data 
types and records and describes Memory windows for inspecting memory with 
type information. Ultimately, Memory windows reduce mental overhead. 

A type in the TMON context is similar to those used in high-level languages: you 
are trying to template how a block of memory of any size is used or divided, what 
kind of information is stored in each division, and how each record is interpreted or 
shown. 

A type is a definition of how memory space is to be occupied. The type itself does 
not actually occupy space, but may define a space with a single field (a simple type) 
or many fields (a record type). 

A record is a block of allocated memory that follows a type definition—a guide to 
understand where values are kept inside the record. 

Showing a record as a series of bytes with a Dump window is simple, but often 
difficult to interpret. Information can be read more easily if the fields in that record 
are shown in a format which is closer to the meaning of the data. For example, if 
four bytes of information will always contain a signed decimal integer, you should 
display that data as a decimal integer, not as hexadecimal bytes. TMON can do 
such mental gymnastics, so you don’t have to. 

TMON comes with a large number of type definitions. These types describe many 
of the records as well as all of the simple data types used by the Macintosh system 


Reboot 

Reboot /Unmount 

Reboot /Immediate 
ExitToShell 


These are discussed in detail 
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environment. TMON types differ from those in high-level languages because they 
also control how memory space is to be displayed and keyed in. TMON permits the 
definition of new types—utilizing the existing primitive and defined record types. 
This allows records used by applications under development to be displayed. 

Automatic and Manual Display of Typed Data 

To a degree, TMON automates memory inspection using types. In the worst case, 
manual inspection of typed data involves a two-part process (no strict order is 
required): 1) selecting the types to use and 2) finding the records in memory you 
want to look at 

Dump windows show the contents of memory in one of the following homogeneous 
forms: bytes, words, longs, or ASCII. Memory windows can be sensitive to how 
memory is used. They will show the contents of memory according to what TMON 
knows or is told regarding the symbol data and resource maps. 

Memory windows work with a core of defined types and type definition 
assignments of things that stay the same (e.g., many of the known absolute system 
addresses and some Macintosh resources). A number of important definitions and 
assignments have already been done for you. Areas of memory at absolute address 
labels are automatically displayed using the preassigned types. 

Some records aren’t shown automatically in context. Reasons may be 1) a type 
hasn’t been assigned to a label, 2) no label exists immediately nearby, or 3) no 
typed resource is involved. Types are not automatically assigned to records created 
by an application, unless they are from resources that have had their types defined 
by TMON. When you want to look at a record in memory, you have to indicate its 
type as well as its memory address. This simply means that you can’t just look at an 
area of memory using a Memory window while having everything provided in 
context. 

Memoiy Window Basics 

The Memory menu item is normally third in the menu. Pressing §§M (the 8€-M 
keys) together will activate a Memory window if one doesn t exist already, or bring 
the existing one to the front. Press Shift-3€-M to always create a new Memory 
window. 

The address and label columns for Memory windows are the same as those, for 
Dump windows. When a Memory window has no better information on what it is 
being used to look at, then memory contents are shown (by default) in a similar 
display of a Dump window— a series of hexadecimal bytes followed by the same 
memory locations displayed as extended ASCII. The variable and register 
indicators, such as N, V, 0, 5, and F, are also displayed in the same manner. 

When TMON knows those locations to be occupied by a CODE resource, memory 
windows will show the contents of memory as disassembled code. Information is 
formatted exactly the way disassembled code is displayed in Assembly windows 
(discussed later in this chapter). The name of the type used to identify sections of 
code is, oddly enough, “Code.” The figure below depicts a screen shot of a Memory 
window: 
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Disassembled Code 


Memory Window Acting as 
Dump Window 


□ Memory from :$001SOCE6 
0019OCE6: $00196920~+$078A: 

6019OCF6: $08196920 A +$079A: 

00190006: $00196920^+$07AA: 

00190016: $00196920^+$078A: 

00190026: »00196920-+$07CA: 

00190036: $00196920-+$07DA: 

00190046: 

00190048: «Block Header* i 

0019ODS0:'CODE' €$001C/$075A : 

00190052:'CODE'€$001C/$075A+$0002 
00190054: 'CODE'«t$001 C/$075A+$0004 
00190058:'COOE‘€$001C/$075A+$0008 
8019OOSA:'CODE'€$001C/$075A+$000A 
0019DO3C:'CODE' €$081C/$075A+$000C 
80190060: , COO£’€$001C/$075A+$0010 
00190064: 1 CODE'€$00lC/$075A+$0014 
00190066:*CODE * €$00ICf$075A+$0016 
00190063:'COO£'€$001C/$075A+$0018 
0019OO6A: 1 CODE 1 €$001C/$075A+$001A 
0019OO6C:'CODE'€$0010/$075A+$001C 
0019006E: ■ CODE ‘€$001 0/$075A+$06 IE 
00190072:‘CODE'€$001C/$075A+$0022 
00190076:*CODE'€$00lC/$075Af$0026 
0019DO7A: , COOE‘€$001C/$075A+$002A 
0019OO7C:'CODE 1 €$0010/$075A+$002C 
00190080:'CODE'€$001C/*075A+$0030 
[00190082: t ^OOE'€>$g91C/$075 fl-»$0032 


$001C/$975A-»$003^: 

Resource Type j Rp J* Address Offset from Beginning 

Piln Klnmhnr neSQUrCe * n., f . ((r .. 


44 49 54 07 
52 52 4E 47 
54 41 52 54 

45 41 44 08 
52 4C 52 06 
5A 06 53 45 
4E BA 

$80 $000400 $0J005AD0 
JTSlartOffset 
JTEntryCount *005 
LINK.W A6,#$#000 
UNLK A6 

LINK.W A6,#lFF90 
MODEM.L D7/-A4,-<A7) 
CLR.L -<A7> 

_NeuRgn 

MOUEA.L <A77+,A4 
MOUE.L A4,-<A7> 
.SetCIip 

PEA N FBBC<A5> 

JSR S085ACA5) 
MOUE.W #$0002,-<A7> 
_TextMode 

MOUE.W S FC14<A5>,O0 
Bfll.S a $0019OO9A 
CMP.W #$0007,08 


53 4£ 47 50 41 47 43 

_ 45 47 54 58 54 08 
06 *3 45 47 40 4£ 55 07 

53 *5 47 57 52 49 54 45 
53/45 47 50 49 43 86 53 
47/54 52 4B @7 25 41 35 


O 


33 45 47 41 01T.SEGPAGE4SEGA 

53 45 47 53 RRNG. SEGTXT-flSEGS 3-1 
53 45 47 52 TART.SEGMNU.SE6R 
06 53 45 47 EA04SE3URITE. SEG 
45 47 53 49 RLR.SEGPIC.SEGSI 

49 6E 69 74 Z.SEGTRK.*4A5Inii 

«/ 


;* CODE * €$001C/$075A+$4A[ 


/ 


Branch Target Address 


File Number 


Number 


of Resource 


Figure 5.6 Memory Window Acting like a Dump and a Disassembly Window 

^lere are over 35 defined TMON primitive types—including Code, Extended, and 
Integer that can be used with a Memory window. There are also a number of 
defined types based on the list of primitive types. Displaying typed information with 
TMON is a no-frills proposition: using a type dictates a single, prearranged way to 
display the information. The complete list of primitive types is provided in Table 5.7 
of the Technical Reference. 

Here are some simple specific examples of typed absolute labels: 

1. TMON knows the information at the absolute label Ticks to be a four byte 
unsigned decimal value. The absolute label TimeDBRA at location $D00 marks the 
location of an unsigned decimal word (16-bits). The data associated with the 
absolute label CurApName at location $910 is automatically displayed in the 
Memory window as a Pascal string. 

2. _ Here’s something more complicated. VBLTask is a record type defined using a 
primitive type defining each field. In the following figure, the VBLTask type is used 
to inspect an individual VBL task record. To set up the example, note the use of the 
provided dcmd VBL (specific details about this kind of command are provided in 
the Technical Reference under “Dcmds”) typed in a Command window, listing all the 
active VBL tasks in a Macintosh system. The information display includes the 
location of VBLTask records existing in memory and then opens the door for you to 
use a Memory window to view a VBLTask record. 


64 


TMON Professional Tutorial 


Chapter 5. HowTo Look At Things In Memory 



Figure 5.7 Memory Window With and Without Type VBLTask 

Note: although the address of a VBLTask record is specifically mentioned the first 
time a Memory window was used, TMON does not automatically know enough in 
order to display that area of memory as a VBLTask. The type name had to be 
explicitly typed into the top line of the Memory window, followed by the VBLTask 
base address, and a Return for the record to be displayed correctly: 

VBLTask,15632 

Another way of creating the Memory window is to make the VBL invocation, click 
on one of the “VBL at” addresses in the VBL window while holding the key 
down. Then, inserting the label VBLTask by clicking (before the colon in the 
topline), key in the text “VBLTask”, and press Return. This way you don’t have to 
type the address, and you avoid a potentially momentary and baffling typo. 

Vitally Important Notes About the Top Line 

The format of the top line of Memory windows is more complex than that of the 
Dump Window (see Figure 5.7). This section describes how to use Memory 
windows with existing types in their simplest form. An example of a specific use of 
Memory windows—the Stack Crawl window, a standard TMON menu item—is 
provided later in this chapter. The Memory command is completely discussed in 
Section 7.1.3 of the Technical Reference. 

Normal Use of Memory Windows 

A Memory window is often used to look at one record of a specific type at a time. 
For this, all you need to type in the top line is 

OptionalTypeName, AddressExpression 

You must type quotation marks around the type name when it contains special 
characters like V, spaces, etc... This is an extremely rare requirement Using 
quotation marks means the identifier must be exact—including case. Typing the 
comma makes sense only if OptionalTypeName is present If you use the TMON 
wildcard character ellipsis, (Option-;) instead of other special characters, 
quotation marks are unnecessary. 
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Which Quote Characters Actually Work? 

Here’s the most important note. To key in quotation marks, do not use the normal 
single and double-quotation mark key—located between the colon/semicolon key 
and the Return key of most Apple Macintosh keyboards. TMON does not translate 
from one kind of quotation mark to another, it reports a syntax error when you try to 
use them. Instead, exclusively use Macintosh typographic quotation marks is 
Option- f, ‘”’is Option-!, “’is Option-] , and is Option-}). 

Unless you are forced to, don’t type quotations marks at all. In the case above, 
TMON added them automatically. Don’t be misled by the way TMON turns what 
you key in— 

VBLTask,15632 


into 


'VBLTask',$15632:$00015632 
—because it entices you into thinking that you can type: 

'VBLTask',$15632:$00015632 (“No Good!**) 


or 


"VBLTask",$15632:$00015632 (•*No Good!••) 

but TMON accepts neither syntax. 

Defining Custom Types 

Chapter 9 of the Tutorial describes how to easily define new types so that 
application-specific records can be displayed meaningfully with a Memory window. 

Those Hidden Window Preferences 

Don’t overlook the button on the top line, way over to the right of the Memory 
window: this displays the Memory window preferences. Because most of these 
preferences are not used and their display uses screen space, they remain invisible 
for most of the time. In general, typing Control-Tab toggles the display state 
(visible, invisible) of the window preferences for the top TMON window. 

The first line contains radio button selections for physical, direct, monitor, user and 
custom memory address spaces (discussed at length in the section covering Dump 
windows). For those machines supporting both 24 and 32-bit addressing modes, a 
checkbox for selecting between the modes is displayed on the same line. These 
options consistently have the same keyboard equivalents as their Dump window 
counterparts. 

The second line of options—selections of byte, word, or long for the default size of 
displayed data elements—omits the Align checkbox found on the equivalent line 
of a Dump window. Although, the checkbox for selecting Standard ASCII is 
present. These options also have the same keyboard equivalents as their Dump 
window counterparts. 
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Because the Memory window disassembles areas of memory with code, the third 
line of options contains checkboxes delineating which processors machine 
instructions are disassembled. There are instruction differences between the 
original 68000 processor of the Macintosh Plus and the 68020 processor in the 
Macintosh II. When the option for the 68020 disassembler is off, it may make it 
easier to catch 68020 or 68030 and 68040 instructions that may be present in the 
code intended to be run only on a Macintosh Plus, SE or Classic. For example, a 
68020 instruction—the first MOVEA.L in the list— 

SUBQ.W #1,DO 

MOVEA.L $00 (A0,DO.W*4),A1 ; This line 

MOVEA.L <A1),A1 

LEA 'FFC8(A6),A0 

appears as: 

SUBQ.W #1,DO 

???? $2270 

???? $0400 

MOVEA.L (A1),A1 
LEA 'FFC8(A6),A0 

when only the 68000 processor checkbox is filled. In this mode, instructions that 
don’t belong are obvious. 

Another example: the 68851 memory management and 68881 floating point 
coprocessors don’t have to be present in a Macintosh for code to be present. 
Checkboxes for these processors are also provided. 

The symbolic names of A000 (A-Line) traps are displayed when the A00 0 
checkbox is selected: 

_RectRgn ; A000 Name 

Otherwise, the hexadecimal A-Line trap value is shown: 

???? $A8DF ; Hexadecimal form 

Finally, assembler macros that TMON knows are shown by their symbolic name 
when the Macro checkbox is selected: 

_SNextTypeSRsrc 

Otherwise the expanded macro code is displayed without the symbolic name of the 
macro: 

MOVEQ #$15,DO 
_SlotManager 

To understand some of these variations without getting involved in the intricacies of 
assembler code, you may want to search RAM for code. While looking at them with 
the Memory window, turn off all processor checkboxes. 'When you do this, you 
should see a screen filled with hexadecimal values and question marks. Selecting 
different processors will then reveal differences. If you are using a 68020 or 68030 
based machine, you are more likely to find 020/030 specific assembler 


; Becomes this 
; and this 
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instructions—or at least instructions that have some cosmetic assembler syntax 
differences. 

More details on TMON code disassembling are provided in the next chapter. 

Special Note: there are two kinds of macros commonly used with TMON: 1) 
assembler macros and 2) TMON command language macros. While this section 
discusses the first type of macros, be aware that the second type exists. 


Display ASCII Follow Record 24/32 Bit 

Size of Hex Chars Only List in Ascending Address Space Addressing Window 

Dump Values or AIL Chars Order Selection Selection Selection Preference: 


□ M priory fro« :$000000&) \ / 

|Addres\ space: OPhysic=* OOirect OMonVor ®Usei* OCusiom 032 
©Byte'OWord OLono OStandard ASCII [jAscending tenplate* 

□ 63000 a68010 @68020 @68030 D68040 @68851 @68881 ®A000 ®Macro* 

® Strict SComnents ® ASCI I Cowients OOse <PC> DUse $+offset ®Use ' DUse - 

fey \ \ _ \ / 

Capture and Show Provide ASCII How To Represent HowTo Represent Select Default 

Print Buffer Comment Equivalents PC-based Offsets Negative Values and Settings for 

Ranges Field in Comment Offsets Window 

Field 


f 


Box 




: bit 


■XX 


®Set Oefaultk 


Figure 5.8 Memory Window Hidden Options with Call outs 
Strict Instruction Interpretation 

Selecting the strict box means you would like to use a strict interpretation for 
disassembly. Instructions that contain non-zero undecoded bits are then illegal— 
shown as hexadecimal values with an mnemonic of ? ? ? ?. 

Disassembly Comments 

You can turn off the Comments field by deselecting the Comments checkbox. All 
text in the rightmost part of the Memory window will be removed. The normal 
default is for this field to be turned on. The other related checkbox, ASCII 
Comments, is used to select the display of some data values (shown in the 
comments field) as ASCII equivalents. 

Displaying Relative Offsets 

You can change the display of program counter relative offsets by using the Use 
(PC) and Use §+0f fset checkboxes. Offsets can appear as any one of the 
following: 

"$0000F3DA 
$OOOOF3DA(PC) 

"§+$16 
§+$16(PC) 

This ability comes in handy when building code intended for the MPW (or other) 
assembler by way of disk-capturing. Section 7.1.2 of the Technical Reference 
describes these issues. 

Negative Relative Offsets 

Negative relative offsets are shown in one of three forms: 
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$FFFFFFE6(A6) 

'FFE6(A6) 

-$001A(A6) 

The checkboxes Use ' and Use - are provided to select the form to be used. 


□ Menoru from :f003DE2A4 _ 

Address space: OPhysical OOireci OMonilor ®User OCuston D32 bit 

O680lc°D68010'' O ^630S St BM030 ,:>S ol80S AS ®2885? ‘868881* ®A000 Btlacros 

^Strlir SComlntf 6 lASClPSments QUse <PC> OH. QUse ' OUse 

Capture :f803DE2A4..$003DE2BA 
Prini :f003DE2A4..f803DE2BA 


003DE2A4: 'CODE *€*8001/f0584+f828C CLR.W 
003DE2A8: 'CODE' $$0001/f0584+f0290 MOUE.L 
003DE2AE: 1 CODE'$$0001/f0584+f0296 MOUE.L 
003DE2B4: ' CODE 1 Qf 0001 /f0584+f029C MOUE.W 
003DE2B6: 'CODE 1 Qf 0001/f0584+$029E CMP.W 
803DE2BA: * CODE 1 j>$0001 5 f0584+f02A2 BGE.S 


□ Set Default; 


fFFFFFFF6 < A6 > 

*004A<A3),fFFFFFFFC<A6) 
$004A<A3) >fFFFFFFF8CA6) 
<A6>,08 
f0004(A3),D0 
^t003DE386 


; ‘ CODE * Qf 000 1 /f0584+f2EE 


®Strict BComents BASCII Corments BUse <PC> QUse S+offset DUse 
I Capt ure :S003DE2A4..S003DE28A 
Print :*0030E2A4..S003DE2BA 


□Use - 


□Set Default 


003DE2A4:'CODE *Qf 0801/f0584+f028C CLR.W 
003DE2A8:* CODE' Qf 0001/$0584+$8290 MOUE.L 
003DE2AE: 'CODE'Of0001ff0584+f0296 MOUE.L 
003DE2E4*. 1 CODE' Qf6001 /$0584+f029C MOUE.W 
003DE2B6: 1 CODE 1 Qf 0001/f0584+f029E CMP.W 


$ftfFFFFF6<A6> 

$©Va< A3>, fFFFFFFFC<A6> 
f00\A < A3 >,fFFFFFFF8 < A6) 
<A6)\D0 

).DB_ 


003DE2B6: 'CUUh 1 wir.w 

003DE2BA: 1 CODE 1 Qf0001ffB584+f82A2 B6E.S (f8B3OE306<PC) ) ..._ 

SStrici IJCoiwents' ®ASCIl“ Coments OUse CPC) ' IJUse S+offsei OUse s DUse 
Capi ure : 1 003DE2A4.. f003OE2BA 
Print :f003DE2A4..$603DE2BA 


;'CODE 1 Qf0001/f0584+$2E£ 


□ Set Default 


$FFFFFF/6<A6> 
f004A<flfe>,fFFFFFFFC<A6) 
f004A 3 ), f FFFFFFF8 < A6 ) 
<A6),/ 

43) ,00 

+f4C 


003DE2A4: 'CODE'Qf 090 l/f0584+f-028C CLR.W 
003DE2A8:'CODE‘Of0001/f0584+$0290 MOUE.L 
003DE2AE;'CODE' Qf0801/f0584+f0296 MOUE.L 
003DE2B4:'CODE'Q$00ei/f0584+f829C MOUE.W 
003DE2B6*. 4 CODE 4 Qf0001Jf0584+f029E CMP.W 

803DE2BA: 4 CODE ‘ Qf0001 ff8584+f82A2 B6E. S __ 

EStrict ® Consent s’ ® ASC11" Comments DUse (PC) QUse S+offset^SUse s DUse 
Capt ure :f003DE2A4..f003DE2BA 
Print :f803DE2A4..f003DE2BA 

003DE2A4: 1 CODE'Qf 0001 /f0584+f828C CLR.W f v FFF6<A6)J^_ 

I003DE2A8: 'CODE'Of 008Iff0584+f0290 MOUE.L 'ttmtrtPtST, WC<A6) 

003DE2AE: 'CODE’Qf0001ff0584+f0296 MOUE.L f004A<A,>>, FFF8<A6) 

003DE2B4:’CODE’Qf000Iff0584+f029C MOUE.W <A6),D0 
003DE2B6: 'CODE 1 Of-0001 ff0584+t029E CMP.W $0804<A3),D0 
003DE2BA: 'CODE’Of0001ff8584+f02A2 BGE.S ^S003DE306 _ 


CODE 4 Of0001ff0584+f2££ 


®Set Default 


4 CODE 1 QfSeQl/f8584+f2E! 


®Strict ®Comnents ®ASCII Comments QUse <PC) QUse S+offset DUse 
Capt ure : f003DE2A4.. f ©03DE2BA 
Print :f003DE2A4..f003DE2BA 

003DE2A4I 'CODE' 0*0001ff0584+f028C CLR. W (-f000fi<A6)J^__. 

I003DE2A8: ' CODE * 0*0001 ff0584+f0290 MOUE.L »O0'4W^A5^T t f0004<A6) 

003DE2AEJ’CODE*0*000Iff0584+f0296 MOUE.L $004A<A3),-$000S<A6) 

003DE2B4:‘CODE’Of000If^0584+f029C MOUE.W <A6),D0 
003DE2B6:* CODE * Qf 0081ff0584+f029E CMP.W f0004< A3),D0 

003DE2BA: 1 CODE 1 Qf0001ff8584+f02A2 BGE.S ^f003DE306 _ 


®Use 


□ Set Defaul 


BStrict ® Cortmenis ® ASCI I Coments ®Use <PC) ®Use S+offset 
, Capt ure :f003DE2A4..f©03DE2BA 
(Print :f003DE2A4..f003DE2BA 


®Use ' ®Use 


’CODE 1 Qf0001f f0584+f2E 
□Set Defaul 


003DE2A4:’CODE’Qf0001ff0584+t028C CLR.W 
003DE2A8:'CODE' Of0001ff0584+f8298 MOUE.L 
003DE2AEI 1 CODE 1 Of0001ff0584+f0296 MOUE.L 
003DE2B4:'CODE'0*000lff0584+f029C MOUE.W 
803DE2B6:‘CODE' Qf0001ff0584+f029E CMP.W 
003DE2BA: 1 CODE 1 Of0001ff0584+f02A2 BGE.S 


-f000A<A6) 

f004A < A3),-f0004 < A6 > 
$004A(A3)r-f0008CAB) 
<A6),D0 
f0004<A3),D0 
S+f4C <PC)_ 


; 1 CODE 1 Qf0681/f0584+f2£ 


Figure 5.9 Select How to Show PC Relative Offsets and Negative Numbers 
Capture and Print 

The Capture and Print lines, as with most TMON windows, occupy the last two 
lines of the window preferences. 


Keyboard Equivalents 

Many of the window preferences are assigned a key combination. These key 
combinations are the same as other window preferences. Here are some of the key 
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equivalents for Memory and Assembly window preferences (see the Technical 
Reference for a complete listing): 


Control-; 

Control-Option-; 

Control-R 

Control-Option-6 

Control-' 

Control-- 

Registers 


displays comments in disassembly 
displays ASCII comments in disassembly 
uses (PC) not A for PC-relative addresses 

uses §+offset rather than target address for 
PC-relative addresses 

uses ' notation for negative numbers 

uses minus sign notation for negative numbers 


Of all the places where data is stored in a computer, registers are the strangest yet 
most significant. Not everything about registers is easy to explain; but because 
they re so important, we can’t get into a discussion on the heap and stack without 
first mentioning registers. 


Registers versus RAM 

A Macintosh system normally has one to 32 megabytes of physical RAM. Registers 
on the other hand, number around 20—depending on the processor. The registers 
in a processor (like the Motorola 68000) are as fast as can be engineered w«cA 
faster in every way than Macintosh random access memory. Registers are used to 
temporarily store values while being manipulated in the processor. The time that 
the average value is expected to occupy a register is measurable in terms of tens of 
assembly instructions, whereas some values in RAM will remain as long as the 
machine s power is on. 


Mostly Orthogonal Registers 

Random access memoiy cells are functionally equivalent to each other—making 
their use at the assembly level considerably easier than the alternative. For 
example, imagine the constraints of having to store all floating point numbers for a 
program, in RAM addresses, from 5000 to 6000! Registers in the Motorola 68000 
tamily (for the sake of making it easier to program at the assembler level) are as 
functionally equivalent as was deemed rational. To a point, this means that they are 
the same. Since the number of registers is limited from the beginning, they are 
automatically a carefully-managed resource. A positive trait of good high-level 
compilers or excellent assembly programmers is the ability to keep these registers 


eight data registers are called DO through D7; the eight address registers are 
called A0 through A7. While data registers normally contain data, the address 
registers are normally used to contain memory addresses. 


Brief History Lesson #1 

In the original 68000, addresses are only 24 bits wide, yet both the data and address 
registers were designed to contain 32 bits. Motorola expected its later processors 
(which are so far the 68010, 68020, 68030, and 68040) to use all 32 bits, and 
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designed the 68000 to be consistent with a 32-bit family architecture. In so doing, 
they avoided drastic modifications to the base instruction set established with the 
68000. In the four years of Macintosh development—before the Macintosh II with 
68020—it was a too-common practice for software developers to use the top, 
unused, 8 bits of address values for status. Being “32-bit clean” means that your 
software doesn’t store status data inside an address. 

Registers with a Special Purpose 

A7 register has a special job, in that it contains the address of the top of the 
current hardware stack. Briefly, a stack is & first—in, last-out queue. It is a contiguous 
chunk of reserved memory that grows and shrinks from only one end, taking up as 
much contiguous RAM it needs for the number of values it contains. To add a value 
to the stack, you push the value on top of the stack. To remove a value from the 
stack, you pop the value. Commonly, the only value in the stack that is manipulated 
is the value at the top. Also, the only place values are added or removed from a 
stack is from the top. Importantly, when a value is pushed onto the top of the 
hardware stack, the address of the top of the stack is lower than it used to be. The 
A7 stack always grows downward. 

Motorola 68000 family processors directly support two kinds of stacks that you will 
normally be involved with: 1) the user stack and 2) the supervisor stack. 

The way stacks work, you only have to know where the top of stack—the “business 
end”— is to know where the stack is. Also, the way the Motorola 68000 family 
works, you usually have to know where one of the hardware-supported stacks is at 
any moment. The A7 register contains the address of the top of the current stack, 
which could be a user or supervisor stack. It is important to note that it isnt 
necessary for A7 to be pointing to the top of a legitimate hardware stack, but it is 
common practice. 

When A7 has a thoroughly goofy value (like FFFFFFF3) or when something has 
gone wrong and the TMON windows have appeared on your screen to leport an 
error, it is likely that A7 is pointing off in the wrong direction. If the supervisor 
stack pointer becomes corrupted, the 680x0 processor will halt 

Hardware Stack Pointers 

The 68000 and 68010 both contain one supervisor stack pointer (SSP). The 68020 
on up contain two SSPs: 1) the interrupt stack pointer (ISP) and 2) the master stack 
pointer (MSP). On machines with two SSPs, only the ISP is used with current 
Macintosh system software. These registers keep track of important information for 
as long as the computer is on. 

Brief History Lesson #2 

Since 1984, normal Macintosh software has used the supervisor stack for 
everything. If you looked, you’d notice that the contents of the SSP usually reflected 
the contents of A7, whereas the contents of the USP rarely revealed the contents of 
A7. (In fact, the USP rarely looks like it is properly initialized.) Using the supervisor 
stack for everything was not Motorola’s purpose. The supervisor stack is intended 
to be used by supervisory tasks, like some important operating system jobs, never 
by application code. 
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instruct ! ons tFe 68000 family of processors are permitted to be used only 
with the supervisor stack-not the user stack. If several programs are in memory 
this arrangement is designed to provide some hardware protection against one* 
program overwriting another’s memory space. 

To complicate matters more, new Motorola processors replace the SSP with two 
different pointers: 1) the ISP (Interrupt Stack Pointer) and 2) the MSP (Master 
Stack Pointer). On a Macintosh II, the ISP always seems to match A7—except 
when running virtual memory (VM) under System 7, where the USP is actually 
used for an application program’s stack. y 

Common Macintosh Register Usage 

Register A6 is regularly used to point to the topmost stack frame record. A stack 
frame record is created on the stack by executing a 68000 family link 
instruction—used to create a block of space (for storing parameters and local 
variables) on the top of the stack in one stroke. When the LINK instruction is 
completed, the top of the stack contains local storage space and the old value of A6 
(pointing to where the last stack frame is). The A6 register contains the location of 
the current stack frame. Any address register can be used as the stack frame 
pointer, but on the Macintosh it is standard to use A6. 

Register A5 is commonly used to point to the base address of memory that contains 
the program globals. When an application is started, this value is copied from the 
initial value of the stack pointer Corrupting the contents of the A5 register 
heightens the chance that the application or the system will eventually crash. 

In place of A5, register A4 is often used to reference globals for non-application 
programs (those written in THINK C or other language systems). 

Other Special Registers and Pointers of Interest 

The program counter (PC) always points to the next address in memory that will be 
executed as a machine instruction. 

The condition code register (CCR) contains bits that are set or reset depending on 
what happened in the previous computation. These bits are as follows: a carry 
extension bit for multiple precision operations, a negative bit, a zero bit, an overflow 
bit, and a regular carry bit. For example, information regarding the last instruction 
executed is stored in the CCR register for conditional branch instructions. 

The status register (SR), a superset of the CCR, contains information on the status of 
the machine. It is a bit-oriented register, in that each bit is responsible for a 
significant piece of status information. 

The floating point coprocessors found in some Macintoshes contain eight floating 
point registers called FP0 through FP7. They contain 80 bits worth of significant 
information—in conformance to the standards set by IEEE. 96 bits represents three 
normal 32-bit fetches from RAM. Reading and writing 80 bits of real information 
requires three 32-bit reads or writes. The floating point coprocessor also has a 
Thl'm 8 {¥?CR) ’ ZStatus reglster < FPSR )’ an d an instruction address register 
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Although not emphasized in this Tutorial, the following registers and pointers can 
be adjusted using the Registers window. 

The vector base register (VBR) is used to contain the base address of the vector 
table. The vector table contains addresses used by the operating system for 
services like exception handlers. Exception processing deals with bad things like 
with division by zero, illegal instructions, privilege violations, and most F-Line 
traps; and good things like A000 (or A-Line) traps. The VBR register doesn’t exist 
on the 68000—the assumption being that the start of the vector table is at location 0 
in memory. In most cases, F-Line traps are provided to handle something bad. 

The three least-significant bits of the source function code (SFC) and destination 
function code (DFC) registers— FCO, FC1, and FC2—can be used as the operands 
of the MOVES instruction. The source and destination indicated by these three bits 
permits data moves between user code, user data, supervisor code, and supervisor 
data areas. These registers are unavailable on the 68000. These bits act as extra 
address lines— providing the different user and supervisor areas with different 
locations in the memory map. 

The cache address register (CAAR) and cache control register (CACR) are used to 
control the operation of the 68020 instruction cache, 68030 instruction cache, and 
data caches. The TMON Registers window displays their contents and permits you 
to change them. 

The 68020 can be paired with a separate memory management unit called the 
68851, but the 68030 on up contains an MMU. The memory management unit 
contains a status register (MMUSR), a CPU root pointer (CRP), a supervisor root 
pointer (SRP). There are others. 

The Registers Window 

The Registers window is used to display all the current data kept in each register. 
You can create a Registers window in one of two ways. When the TMON menu is 
on the screen either 1) select the menu item Regs or 2) press the and R keys at 
the same time. If a Registers window already exists, either of these actions brings 
will bring it forward. Holding the Shift key down at the same time enables you to 
make any number of Registers windows. 

Starting from the top line: the leftmost square is the TMON GoAway box for the 
window. To its right is the word Registers. 

Next on the top line are the radio buttons labelled main, 1, 2, and 3 —selections for 
a register set to show in the window. Main selects the real register set, whereas 1,2, 
and 3 each select an auxiliary register set to temporarily save the values of the real 
register set. 

Because of the complexity of the Registers Window, it is presented here one piece 
at a time. 


TMON Professional Tutorial 


73 


Chapter 5. How To Look At Things In Memory 


Register Set Selection 


Helpful 

Instructions 

opt 


Program 32 Bit Address 

Counter Status Register Bits Selection 


□ Registers ®nain'Oi 02 03 *: 


Data _ 

[ftddr 0071402C 


USP**5C000706, 

SFOS07, 


ite opt ion:swap PC=S00714034 
3 4 « 

0068777A 


SR=*«ttSn^000.. ,xnrvc» 325 \±\ 


0071EO2A 006077A0 00000000 00000000 


39A20000 

0071F94C 


MSP=*DEFFEFFF, 
CFC=*07, 


ISP=*00607024, UBR=*00000000, 

CACR=*000031U««. ,1460000.. .B080I* 


0056CE74 _ 

00000i£4 00607624 

CAAR=*FBFF7FFF 


Other 680X0 Register Contents 




Address and Data 
Register Contents 


Figure 5.10 CPU Section of Register Window 
Copying, Swapping, and Setting Register Sets 

Several key sequences allow you to select, write, read, and exchange register sets 
The standard keyboard key sequences are listed in the Technical Reference. 

Alternate register sets allows you to save the current application’s register set. This 
conveniently frees you to execute other code for testing purposes, subsequently 
restoring the previous state from the alternate register set. 

Two reminder phrases are in the top line of the window. The phrase §g : write 
reminds you how to assert values from one set of registers to another. The phrase 
option: swap reminds you how to swap values between two sets of registers. The 

former requires that you hold the X key down, and the latter requires that you hold 
the Option key down. 

To sMiap the contents of the selected register set with the currently displayed set, 
hold the Option key down while clicking on one of the register set buttons. To 
write the contents of the displayed register set into the one being selected, hold the 
56 key down while clicking on one of the register set buttons. Holding both the 3g 
and Option keys down while clicking on one of the register set buttons, reverses 
the effect, writing the contents of the selected register set into the one being 
displayed. An alert is displayed indicating the performed action. 

Program Counter 

The next item of the top line is the the program counter’s (PC) address—shown as 
“PC=”— followed by a hexadecimal address. It is possible to change the contents of 
the program counter simply by placing the text cursor anywhere within the 
hexadecimal value and editing as usual (type, highlight, delete, etc.). Pressing 
Return will effect the change to the program counter. 

Status Register 

Farther to the right, the five least significant bits of the status register contents are 
shown symbolically. Each bit is represented by a single letter. If the letter is in 
lowercase, the bit value is 0; if the letter is in uppercase, the bit value is 1. The 
exception is the three bits used to form the interrupt mask—shown as a three—digit 
binary number. 
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X Extend bit: X if set by instruction result 
N Negative bit N if negative 
Z Zero bit Z if zero 
V Overflow bit V if Overflow true 
C Carry bit C if Carry set 

Note that the status register is 16 bits wide. The top eight bits contain the interrupt 
mask, the processor mode, and instruction tracing mode. These are not meant to be 
changed by application code. 

24 or 32-Bit Addresses 

The last thing that can appear on the top line is the 32-bit checkbox, which 
appears only on Macintosh systems supporting both 24 and 32-bit addressing 
modes. This checkbox appears in the Registers window and indicates the current 
MMUMode. Selecting these addresses is similar to the action of the 
SwapMMUMode trap. It does not affect the displayed memory of other TMON 
windows. 

When in 24-bit mode, the top eight bits of an address could contain arbitrary 
values, which may be misleading on inspection. 

Special Note: indiscriminately toggling the 3 2-bit control and exiting TMON may 
cause the Macintosh to crash. 


All Those Addresses... 

The rest of the first part of the Registers window displays the CPU registers. The 
exact list of available registers depends upon the processor. For the Macintosh 
with a 68020, the registers are D0-D7, A0-A7, USP, MSP, ISP, VBR, CAAR, SFC, 
DFC, and CACR. 


...Can Be Changed 

Register values can be modified in one of three ways: 1) by using the text cursor to 
edit the hexadecimal value, 2) by typing reg=value in the top line (for example, 
A3=$000102F4) or 3) by typing 32bit=l (true) or 32bit=0 (false) for the 24/32- 
bit checkbox setting. The next section in this chapter discusses expressions, 
enabling you to go hog wild. 


Display the Most Recent Message 

The following section describes the most commonly displayed message after 
TMON’s last activation. When TMON is activated, the Registers window displays a 
message. For example, if you hit the Macintosh s interrupt switch, the message 
may read: 

Trap signal at $00406616 

indicating that the interrupt switch has been hit—although this particular message 
may also refer to other actions besides the interrupt switch. This message is 
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displayed in a TMON alert box covering the TMON control menu until an action is 
taken (e.g., pressing the mouse button). 


_ Last T MON Pro Message 

I Trap signal at- *007140/4 


Message Section 


Figure 5.11 Message Section of Registers Window 
Floating Point Coprocessor Information 

If your machine contains a floating point coprocessor, the floating point 
coprocessor information appears next in the Registers window—just below the 
htest generated message. 'Hie following paragraphs provide a detailed description 
Iar ^quant ity of information contained within a Registers window! 
point section thr ° Ugh 5-14 re P resent a three-part display of the window’s floating 

The first line displays—in hexadecimal—the contents of the floating point 
instruction address register (FPIAR), the floating point control register (FPCR) and 

normal fash km ** * (FPSR) - values can be edi ted directly in the 


Floating Point 

Instruction Address Status FPSR Condition Codes: 
Register _ Register Negative Zero Infinity NAN 


FPSR 

Quotient Byte 


Figure 5.12 First Line in the Floating Point Section of the Registers Window 

Phe last two parts of the top line (as well as the entire second section) displays the 
values of the registers with as much context as room permits. With these 
c eckboxes and radio buttons, it is possible to change something without having to 
exactly know the action of each bit of the registers. 


Branch/ Inexact Inexact 

bet on Signaling Over Divide Operation Decimal 

Unordered NAN Flow ByO / l^lnput 

c ^ UNFL 'e inexJ 

Status 8 □ B B S □ @ 8>>*" ndln9 ®"« 

nccruad InvOp □ ^ D □ □ 

Invali Operand Crider 

Operation Error Row U_.1T 


1 FPCR Rounding: 

*l to Nearest Jo Minus Infinity 
^to Zero to Positive Infinity 


Rounding ©nearest 09 O-INF O+iNF 
Precision ®E OS QO 


FPSR FPSR FPCR 
Accrued Status Enable 
Exception Byte Byte 
Byte 




FPCR Precision: 
‘Double 
“Single 
■Extended 


Figure 5.13 The Middle of the Floating Point Section in the Registers Window 

The FPCR Exception Enable Byte turns on and off the exception handling for each 
NAMn rr0r ?£ dltl ° n " m ® ntioned above: Branch/Set on Unordered, Signaling 

EttS" " erflow ' DividebyZero ' Inexact0pera,ion ' an<l 

The FPSR Exception Status Enable Byte checkboxes shows and asserts which 
oating point exceptions are pending. The bits are normally set as a result of an 
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operation. These bits correspond exactly to those in the FPCR Exception Enable 
Byte. 

The FPSR Accrued Exception Byte tests for an exception condition after several 
floating point operations have been done, instead of after each one. The Invalid 
Operation bit corresponds to the Branch/Set on Unordered, Signalling NAN, and 
Operand Error bits. 

You can select which rounding methods should be used by selecting its appropriate 
radio button—the rounding mode or the rounding precision mode. The controlled 
bits are contained in the FPCR Mode Control Byte. 

Finally, each floating point register is displayed by its name—a 96 bit hexadecimal 
representation (referred to as a 12-byte datum in the Technical Reference) and the 
decimal value. 


FP0^$400E0000_80000081_F 25E1869. X 
FP1«*7FFF0000_FFFFFFFF_FFFFFFFF.X 
FP2"*7FFF0000_FFFFFFFF_FFFFFFFF.X 
FP3“*7FFF0000_FFFFFFFF_FFFFFFFF.X 
FP4**7FFF@080_FFFFFFFF_FFFFFFFF.X 
FP5-*7FFF0000_FFFFFFFF_FFFFFFFF.X 
FP6=*7FFF0000.FFFFFFFF_FFFFFFFF.X 
FP7*I7FFF0000_FFFFFFFF_FFFFFFFF.X 


32768.0080257650214 > 
HsNCFFF) 

HaN(tFF) 

NbN<*FF> 

N*N<*FF> 

N«N<*FF> 

NaN<*FF> 

NaN<*FF>„ 


* Floating Point Registers 

_ Floating Point Section 


Hex Representation Float Representation 


Figure 5.14 Bottom of the Floating Point Registers in the Registers Window 
Memory Management 

For Macintosh systems, memory management is provided in several ways. The 
68000 includes no real memory management unit. The original Macintosh II is 
equipped with an IC in place of the Motorola 68851 MMU, leaving the regular 
Macintosh operating system system without true memory management. To run the 
A/UX operating system (UNIX for the Macintosh) on the Macintosh II, the 68851 
MMU is available separately. For 68030-based systems (e.g., the Macintosh Ilfx), 
the memory management facilities are built into the CPU. This MMU is 
functionally similar to the Motorola 68851, but is another generation of memory 
management with no noticeable differences. There are several registers in the 
68851 that do not exist in the 68030 MMU. 

When a 68851 MMU is present in the Macintosh, the TMON Registers window 
displays the appropriate register information, permitting access to the 68851. 


MMU Status 
Register^ 


Translation 

Control 

Register 


Transparent 

Translation 

Registers 


(1MUSR=«BLs}wiM. .T... 111» P 
TC=*80F84500 <E® SPED FCtO PS=*F IS=*8 TIA...D=*4500> 

TT0=*FFFF0777 <Base=<FF Mask=*FF £□ Cl® R® RUM® FCBase=7 FCM*k=7) 
TT1=*FFFF0777 <6ase=tFF Mask=4FF £□ Cl® R® RUM® FCBase=? FCMdsk*=7) 
CRP5*7FFF0002 007FFC70 <lO Linit=$7FFF DT=2 Addr=*007FFC78) 
£RP^420042C2_7C213EA3 <UQ LiMit=$4200 DT=2 Addr=S 7D233EB0) 


Regis t€ 

rcMafek= 

1 FCMdsk= 


68030 MMU 
Memory 

Management Section 


Translation Table Root Pointers 


Figure 5.15 68030 MMU Version of the Memory Management Section 


TMON Professional Tutorial 


77 


Chapter 5. How To Look At Things In Memory 


MMUSR=<bLsAuIngc.., .010» CAL=-*000 

AC=«.M.00. .11» UAL- 

CRP=$7FFF0202_40880050 <UO __ 
SRP=*A040U94_201S430A <U® SG 
ORP=$40000082_F6C3200C <UD SG 
0 12 3 

BAC 0086 4SE8 0004 59F9 
BAD 2E0C 5029 8080 5504 


PCSR=*«fl.0000* SCC*5J111111U 

-- TC»*80F84500 <E@ SREQ FCLO PS=$F IS=$8 TIA„B**»4500) 

Limit=$7FFF DT=2 Addr=$40800050> 
sQ Limit=$2040 OT=0 Addr=$20194300) 

Unit=$4000 0T=2 Addr=$F6C32000) 

5 6 7 

0F4E 4041 1480 

4A00 58B4 80C2 


0400 


Figure 5.16 68851 MMU Version of the Memory Management Section 

Exception Stack Frames and Those Checkboxes at the Bottom of the 
Registers Window 

The second-to-last section in the Registers window shows the exception stack 
frames. Appearing in the last section of this window—just below these frames—are 
three checkboxes. These deal with exceptions, breakpoints, and traps (see Chapter 
8 of this Tutorial for a detailed discussion). 

The command rte (discussed in Chapter 7 of this Tutorial) uses exception stack 
frames to restore the existing environment prior to an exception. To illustrate: there 
are times when the CPU can be interrupted in the middle of an instruction. This is a 
situation in which the normal CPU registers do not contain the whole story. 
Instead, exception stack frames provide the complete details. The Registers window 
displays the contents of the exception stack frames for the true masters of 
assembly-level debugging. 



Figure 5.17 Exception Stack Frame Section of the Registers Window 

The first checkbox (see Figure 5.18) permits you to select the exception stack frame 
when exiting TMON. You may need this option in either of the following cases— 1) 
if you use the interrupt switch on the side of the Macintosh to bring up TMON or 2) 
if you use Programmer’s Key to interrupt the executing task now instead of 
allowing TMON to select the next “safe” time. When exceptions are generated 
manually without regard to the time of TMON’s processing, the exception stack 
frame contains important CPU and coprocessor state information (see Section 7.1.7 
of the Technical Reference). 


□Us* exception stack frame when exiting 
□Do all breakpoint and intercept actions for the next instruction 
Hi Ignore intercepts and signals for the next instruction_ 


Useful 

Debugging Toggles 




Figure 5.18 Debugging Toggles Section of the Registers Window 

The next two checkboxes temporarily turn on and off the breakpoint and trap 
watches (see Chapter 8 of this Tutorial). 
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Expressions 

TMON is ready for you to define menu items, commands, keyboard sequences, 
type definitions, and variables. Much of this is due to its built-in command 
interpreter. This interpreter and the predefined windows provide a vanguard of 
easily expressed power. 

Now that we have introduced registers and the Registers window, it is possible to 
explore TMON expressions. We will use the Dump, Memory, and Registers 
windows as examples—preparation for the following discussion of a Stack Crawl 
window, including an expression and a type declaration. 

Recall that entering TMON and selecting the Dump menu item brings up a Dump 
window. The highlighted number is the hexadecimal base address of the new 
Dump window. Scrolling the window contents up or down changes the base 
address and moves the display of memory up or down. 


Identifier Names 

In place of the highlighted base address of the Dump window, typing the letters pc 
and Return causes the current program counter to be used as the base address of 
the window. To confirm this, create a Registers window and compare the value in 
PC with the base address of the Dump window. 

Note that the first data line of the Dump window—just to the right of the memory 
address column—has the letter ‘P’. This means that the window is showing an 
address that matches the program counter. If you see the numbers ‘0’ through ‘7’ in 
place of or in addition to ‘P\ it means that the address register contains a similar 
address. 

The program counter and register names are register identifiers. Other kinds of 
identifiers you can type are CurApName (a label in low memory), command names 
(in a Command window only), a type name, numbers, constants, etc. 

But What About Case Sensitivity? 

A case-insensitive match is one where you can use uppercase and lowercase letters 
indiscriminately :“AAA” is the same as “aaa”. A case-sensitive match is one where 
the case of the letters must be the same: “AAA” does not match “aaa”. 

The identifier search algorithm in TMON permits case insensitivity in normal use, 
so that you can type curapriame and still match CurApName. Depending upon 
identifier precedence, TMON will find an exact match before it finds one that differs 
in case. 

TMON searches for identifiers in the following order: macro, keyword, function, 
register, variable, number, label, type name, and constant. The first six items are 
case-insensitive identifiers; the last three items are case-sensitive. 


TMON Professional Tutorial 


79 


Chapter 5. How To Look At Things In Memoiy 

Wildcard: 

There are times when matching anything will do the best job. TMON uses the 
ellipsis character, (Option-semicolon) to mean match anything. For example, 
typing “HGet...” will match HGETFLAGS and HGetState. 

When is an Expression an Expression? 

Each window has its own set of rules for typing things on the top line. Generally, 
simple windows use simple address expressions; while complex windows require 
more complicated address expressions. For example, the Dump and Assembly 
windows use a single-address expression. A typed expression (e.g., A2) eventually 
evaluates into a single integer. Because Memory windows are much more context 
dependent, they require more information. There is more to parameter lists for 
Memory windows than simple address expressions. 

Address Expressions 

Mentioned briefly, address expressions eventually evaluate to an integer. Values 
can be typed in a variety of bases: hexadecimal, decimal, octal or binary. Arithmetic 
operations can be done in an address expression, so you can type in A2+2 and have 
it come out correctly. Since address expressions can get complicated, a detailed 
investigation follows. 

Delaying Evaluation with A 

TMON uses a number of the weird characters (available on every Macintosh) as 
operators. In the following sections, we introduce you to some of these characters. 

The first character under discussion is the delta character (A). This character, 
created when Option-J is typed, stands for delay evaluation. When parts of an 
expression influenced by a A change in value, the expression is re-evaluated with 
respect to those changes. Readily seeing changes and their consequences is useful. 

An Exercise 

The A makes a difference. Let’s practice. 

First, enter TMON and create a Dump window. Base the Dump window on the 
program counter by typing in PC in place of the current hexadecimal address. Open 
a Registers window and drag it where you can see both windows. Be sure you can 
see the program counter value in the Registers window. 

Second, exit TMON by selecting the exit menu item (or type 38-e), then re-enter 
TMON. Note that the Dump window is showing where the program counter used 
to be, not where it is now. If it is, this occurred by coincidence. 

If you don’t want to leave that trick up to luck, replace the base address of the 
Dump window with Apc and press return. Not only is the Dump window showing 
where the program counter currently is, but the expression as shown by the top 
line of the Dump window didn’t turn into an eight digit hexadecimal integer. 
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Exiting and re-entering TMON will show that the base address of the Dump 
window now follows the program counter wherever it goes. 

Because the delay character’s precedence is so low, it will delay anything in an 
expression unless it is contained by parentheses (e.g. Ape + pc and Return 
produces Ape + pc, but (Ape) +pc and Return produces (Ape) + 
$02300032). 

Immediate Evaluation with ¥ 

Although typing PC as the address expression of the Dump window provides an 
immediate evaluation of the expression (when Return is pressed), there is a need 
for TMON’s immediate evaluation character, ¥ (Option-Y). It is easy to get into a 
bind with operator precedence when working with complicated expressions. The use 
of ¥ in such situations clearly asserts the necessity of immediate evaluation, despite 
other operator influence. 

An example of the ¥ operator’s usefulness is as follows: 

APOApplZone'' && PC<ApplLimit A 
APC>¥ApplZone" && PC<¥ApplLimit^ 

Both of these expressions test the range of memory of the PC, using the less than 
and greater than operators. ApplZone and ApplLimit are pointers to the bounds of 
the current application zone and are provided by the Macintosh operating system. 
The first expression is true whenever the PC is in any application heap zone. The 
second expression uses the ¥ operator and is true whenever the PC is in the 
particular heap zone which was current when the expression was first evaluated. 
You will find these two expressions so useful that TMON has declared them as two 
predefined macros named InApp and InThisApp. 

Operator Precedence Level 

An operator’s precedence level indicates its priority in grouping its operands. For 
example, The TMON operator * has higher precedence than +. So, the expression a 
+ b * c + d actually means a + (b * c) + d. 

Both the A and ¥ operators have the lowest precedence level of all operators in 
TMON. Therefore, they have an effect which spans across all other operators. Even 
with the availability of parentheses, it is sometimes necessary (or at least 
convenient) to use ¥. 

Since A and ¥ have the lowest precedence known to TMON-kind, Aa+b*c+d means 
A (a + (b * c) + d). Finally, Aa + b * c + ¥d means A (a + (b * c) + ¥d). 

Parentheses Operators 

Parentheses are operators that change the normal associativity and precedence 
orders of operators used in an expression. Parentheses have the highest 
precedence among all operators. No operator can win an argument against 
parentheses. 
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Different Kinds of Expressions 

Address expressions evaluate into an integer value. TMON expressions can 
evaluate into an integer, data item, an error number, a floating point number or a 
string. To discover what those are, let’s lay more groundwork on data types and 
operators. 

Essential Data Types and Radixes 

The default TMON data type is integer. The default base is hexadecimal, so using 
the base-16 (radix) value operator, *$’, is optional. Typing 23 really means typing 
$23. A hexadecimal integer must have less than 9 digits. Single underscores may be 
placed inside integers for pretty printing purposes without changing the value. All 
of the following are legitimate hex integers: 

23 

$23 

$lFeb_cda5 

128 

None of the following are legitimate hex integers: 

23_324 

12_56_70_22_89 (this is a datum, described shortly) 

134g 


Because the default base is hexadecimal, instances of decimal numbers must 
always be prefixed by the base-10 value operator—the period If you inspected 
TMON before reading this section of the manual, you might have noticed that the 
numbers in the Options window used to set the width and maximum height of 
TMON windows have a period in front of them. This is because they are base-10 
values; not because they are floating point numbers. (Floating point values must 
have at least one leading zero before the decimal point—this indicates the 
difference between a decimal integer and a float.) 

Integer numbers can be entered and displayed as octal, hexadecimal, decimal or 
binary (e.g., .10 is decimal, %10 is binary, and %10 (Option-Shift-E) is octal). 

Datums 

A datum is an arbitrary sequence of bytes whose length is significant but not 
limited in any way—short or long. For example, a datum may be used to specify the 
hexadecimal representation of a floating point value (the datum 
$4004_A8000000_00000000 represents the unremarkable floating point number 
42.0). Datums can be specified as hex or binary numbers or as ASCII literals. 

Value Operators 

Value operators such as parentheses either return a value or affect the associativity 
and precedence of other operators. These value operators have the highest 
precedence. In the following tables, all known operators are listed in decreasing 
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precedence order. In addition, the register value and monitor variable operators of 
the value operator table are the value operators that can be delayed. These are 
affected by the A and ¥ operators. Three items also mentioned in the table are 
register.suffix, monitor variables, and “One-filled” things. These are described 
immediately following the table. 


Precedence 

Value Operator 

Description 

21 (highest) 

0 

Parentheses 

20 

nameO 

Function invocation 

19 

register 

Register value 


register.suffix 

Register value 

18 

name 

Monitor variable value 


oname 

(° = Shift-Option-8) 

17 

number 

Hexadecimal integer or datum 


$number 

Hexadecimal integer or datum 


.number 

Decimal integer 


^number (Shift-Option-E) 

Octal integer 


%number 

Binary integer or datum 


'number 

One-filled hexadecimal integer 


$'number 

One-filled hexadecimal integer 


.'number 

One-filled decimal integer 


%c number 

One-filled octal integer 


%' number 

One-filled binary integer 


fit. pt. num 

Floating point number 


'chars' 

Literal integer or datum 


"chars" 

String 

16 

identifier 

Label, type name, or constant 


“identifier” 

Label, type name, or constant 


‘identifier’ 

Label, type name, or constant 


Size Suffices 

Normally, TMON expressions evaluate into 32-bit integers. Size suffices can adjust 
results into more appropriate forms. 

Size suffices can control the size or format of a typed-in value explicitly—regardless 
of the typed value. In the value $ABCDEF.UW, the “.UW” is the suffix for 
interpreting the value as an unsigned word. A2.SW is an example of a suffix 
affecting the value of a register— the value of A2 as a signed word. Size suffices are 
applicable after the dereference operator, A , which is discussed in the unary suffix 
operator table. Size suffices can define numbers in certain sizes without typing in all 
the zeros: for example, $ f f. 1 turns into $000000ff. 

The complete list of suffices can be found in Table 5.10 of the Technical Reference. 
Here’s how suffices work: suffices assert a length of a byte, word, or long, or a 
single, double, SANE extended or 68881 extended floating point number. Let’s start 
with a number of arbitrary size— $abcdef. Add the suffix .b for unsigned byte 
(size suffixes are case-insensitive). TMON truncates the most significant bits of 
$ABCDEF down to $EF. The suffix .ub is the same as .b; while .sb differs from .ub 
and .b by performing a sign extension after the truncation. 
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Monitor Variables 

Monitor variables are like variables you’d expect to find in a language system like 
BASIC. Define user-defined variables at any time through the Number or Vars 
windows. These are used to contain values and store the results of evaluated 
expressions. There are a small number of predefined monitor variables. A short 
description exists in the Dump window discussion: N, V, and 0 are monitor 
variables. Referencing any of the predefined monitor variables does not require the 
use of the ° operator. The ° is used only when you want to reference a user-defined 
variable. 

Two examples you can enter from the command line are 

Vars ^Seconds = ATicks'V.60 
Vars ^Language = "Pascal" 

The first of these variables takes on the value of the low memory global Ticks 
divided by 60. Ticks is a low memory global containing the number of 60ths of a 
second since the machine was powered on. Your applications usually should not 
directly use low memory globals; instead, they should use the appropriate system 
calls to get the required information. For an interesting effect, create the variable 
nSeconds and anchor a Dump window to Anseconds*$10. The second variable 
just shows that variables can be of differing types, including strings. 

One-Filled Operators 

The “one-filled” operators are the normal value operators with the single back- 
quote character This character indicates the setting of the leading zero bits of 
the number. $AB = $AB, right? Well, $ AB = $FFFFFFAB. This is used in Assembly 
and Memory windows as the Use ' window preference for showing negative 
relative offsets and values. 

Unary Suffix Operators 

In the Pascal tradition, unary suffix operators A and A .suffix are used for 
dereferencing pointers. They follow the value operators that are listed above in 
precedence order. These operators can be affected by the presence of the A and ¥ 
operators, since they are directly involved with information that can change over 
time. These operators also have left-to-right associativity—the leftmost operator is 
going to be evaluated first when everything else is equal. 


Precedence 

Operator 

Description 

15 

A 

A . suffix 

Dereference 


Size suffices, just described a few paragraphs ago, can be used to coerce the size or 
format of a dereferenced value. The A operator permits you to use a suffix to 
indicate using a non-longword data type. Take note: if the value $ABCDEF01 starts 
at location 4 in memory, and you say 4 A . w, you will get $ABCD and not $EF01. 
Saying $ ABCDEFO1 . w will directly return the value $EF01. A rather useful example 
of the . W suffix is the expression MemErr''. w which refers to the word at location 
MemErr. 
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For further information on dereferencing, look below the next table for the 
description on the * operator. 

Unary Prefix Operators 

Unary prefix operators are next in precedence. The * and f operators can be affected 
by the A and ¥ operators. These operators are all right-to-left associative (given 
that all things being equal)—the operator on the right will be evaluated first 


Precedence Operator_ Description 


14 

+ 

Unary plus 


- 

Negation 


t 

Logical complement 



Bitwise complement 


* 

Dereference (asterisk) 


t 

A000 trap location (Option-T) 


NaN 

NaN constructor 


The A000 trap location operator returns the address of an A000 trap when given a 
proper trap number or name, (e.g., something fitting within the range $000 to $FFF, 
the range $A000 or $AFFF or any existing, recognized trap name—like 
f_NewHandle). This operator is useful for examining what an A000 Trap, or an 
A000 Trap Patch, actually does by opening an Assembly window to f_trapname. 


Resource Lookup Operators 

Macintosh software is partitioned into resources. So, the operating environment 
spends a certain amount of time looking for them, loading them into memory, and 
removing them from memory. The Macintosh trap routines -_GetResource, 
_GetNamedResource traps, etc., search for a resource in a predetermined search 
path. 

TMON provides a couple of operators to perform the same duties. The code used to 
perform these functions is contained by TMON. This debugger relies on its own 
co d e —avoiding any potentially perilous calls to the Macintosh Resource Manager. 
The lookup operators act is slightly different from GetResource and 
GetNamedResource. Resources are searched in more resource files and 
MultiFinder partitions than they are with Macintoshes trap calls. In addition, the 
value is returned to the resource data as a pointer, not as a handle. 


Precedence 


13 


Resource Description 

Lookup Operator 


i (Option- 
R) 

®f (Option- 
R Option-F) 


Resource lookup 


The ® (Option-R) is the binary resource lookup operator. For example, 
'CODE'®42 provides the address of the code resource 42. The first field is the 


TMON Professional Tutorial 


85 




Chapter 5. HowTo Look At Things In Memory 


resource type, and the second field is the integer ID of the resource. To track a 
resource by name, try something like 'CODEWWaldemar". 


The ®/ (Option R, Option-F) is the tertiary resource lookup operator—used to 
track a resource within a specified file (using the file identifier number) For 
example, ’CODE'®42/1234 and 'STR '®"Eugene"/451 attempt to provide the 
addresses of resources in file #1234 and #451, respectively. 


Both the ® operator and the ©/operator are right-to-left associative. 


Miscellaneous Operators 

The following shows several binary, left-to-right associative operators in 
precedence order. These should look familiar, with the exception of assertion and 
selection delay and immediate evaluation. 


Precedence Operator Description 


12 

* 

/ 

\\ 

Multiplication 

Division 

Floating point division 

Remainder 

11 

+ 

Addition 


- 

Subtraction 

10 

« 

Bitwise shift left 


» 

Bitwise shift right 

9 

< 

Less than 


<<= =< 

Less than or equal to 


> 

Greater than 


>>= => 

Greater than or equal to 

8 

== 

Equal to 


* <> != 

Not equal to 

7 

& AND 

Bitwise AND 

6 

XOR 

Bitwise exclusive OR 

5 

1 OR 

Bitwise OR; string concatenation 

■PH 

&& 

Short-circuit logical AND 

HEflHHH 

1 1 

Short-circuit logical OR 

m■ 

?? 

Assertion 

■m 

?; 

Selection 

0 (lowest) 

A (Option-j) 

Delayed evaluation 


¥ (Option-y) 

Immediate evaluation 


The assertion operator, ??, is used in the form exprl??expr2. If exprl is nonzero 
(true) then expr2 is evaluated and returned. If exprl is false, then a TMON monitor 
error 58108 is returned, resulting in the error message “?? assertion failed.” 

The selection operator ?: is used exactly like its C language counterpart—in the 
form exprl?expr2:expr3 where expr2 is evaluated if exprl is true, and expr3 is 
evaluated if exprl is false. 


86 


TMON Professional Tutorial 






Chapter 5. How To Look At Things In Memory 


Compiling Fast Expressions 

TMON can take steps to make an expression as fast as possible. Fast expressions 
come in handy when you are performing operations with TMON that are naturally 
slow (e.g.,recording and using breakpoints and trap intercepts). The speed of trace, 
step, and gosub re-entry conditions can be improved as well. 

A fast expression may not include floating point anything: numbers or operations. 
Neither may it include datums (which are defined in short order), strings or 
monitor variables. But, you may include the monitor function error, as well as the 
registers D0-D7, A0-A7, SP, MSP, ISP, SSP, USP, SR, CCR, and PC. But the 
operators f. ®. and ®f are excluded. Expressions that conform will be 
automatically compiled by TMON. (see the TMON Reference for more information 
on expression compilation). 


Stack Lore 


If you are relatively new to computers and debugging, then you probably found the 
last two sections diffi cult. You may have had a hard time with this section as well. 
That’s okay. Even introductory texts like this Tutorial have to sling around 
acronyms a bit to get the idea across. It may take a few readings of these sections to 
understand everything. 


Whaf s a Stack to Do? 


The stack is used for temporary storage. For example, when making a function call 
in C, space is allocated on the stack to make room for function parameters. More 
space is allocated for locally created variables to be used within the function. When 
the function returns, the space on the stack for the function is reclaimed. 
IMPORTANT: Each function call gets its own stack frame for storing parameters 
and local variables, according to the order on the stack that they are created. In 
normal program execution, the stack can be several stack frames deep. In extreme 
cases (e.g., recursive function calls), there can be several hundred or even several 
thousand stack frames on the stack (space permitting). Since a stack frame 
contains useful information—such as all locally declared variables and 
parameters—a window for inspecting the contents of the stack neatly is a great 
help. The one provided with TMON is called the Stack Crawl window. 
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Stack Crawl Window 


Selecting the stack Crawl menu item in the TMON menu brings up a Memory 

window that may look like the following: 
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Figure 5.19 Stack Crawl Window 


In the top line of the Memory window, the first field is also an optional field—the 
typ e name. TMON comes with a number of predefined types, of which StackFrame 
is one. In Figure 5.19, the Memory window is told to use the StackFrame type to 
display stack frames intelligently. Stack frames are displayed starting at the address 
indicated in the last field above, the address expression. 

The next optional field is the base address —used to indicate the address of the first 
item of the given type name. In this case, the base address is a delayed reference to 
the register A6 which on the Macintosh normally contains the address of the 
current stack frame. 


The following field contains the next expression, which is what the Memoiy window 
should do to continue. If the field isn’t given, the Memory window stops after a 
single iteration. If the field is specified, then the Memory window continues. In this 
case, the Memory window continues to display the next stack frame. 

What Does A§ A mean? 

Let’s take this a character at a time. 

Windows use simple values to do something. For a window to make use of it an 
expression must be evaluated into a simple value. 

An expression is normally evaluated when you press Return after the expression 
has been typed into the top line of a TMON window. The expression is replaced by 
the result, which the window uses for its intended capacity (e.g., a base address). 

For a specific example, typing pc and Return will cause the expression, pc, to be 
evaluated to the value contained by the program counter—say, $013E3930. This 
address can be used as a base address for a window. 
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This trick works only once. Once you type PC Return you will lose the original 
expression! This means that you have to type PC Return again for a new value to 
be evaluated. 

Delay Operators Revisited 

The first character in the next expression field of the top line is A. It is the delay 
operator (mentioned earlier in the section on expressions). When a delay operator 
is used, it allows the window to use the result without physically replacing the 
delayed part of the expression. The delay character’s precedence is so low that it 
delays anything in an expression unless it is influenced by parentheses. 

Current Reference Address Character 

§ is predefined to contain the current location. You may think that § is a synonym 
for PC then, but it isn’t. The § operator cannot be used in any expression 
establishing the first base address. 

§ is actually the current window reference address. This value has to be established 
for the expression A§ A first in order to mean anything. Once established, § may 
be used. One reason that § cannot always work in place of PC is that PC always has 
a legitimate integer value, while § does not. 

In other words, you can’t use § after the colon in the top line of any exploratory 
window. You would be trying to establish a new base address for the window with 
an unestablished address. § must be pre-established by a valid base address before 
it can be used. 

Note, by the way, that register A6 is used to point to the next stack frame, and not 
PC. ’ 

Put it All Together 

Since the A is the dereference operator, the first two characters mean “dereference 
the current address.” 

Put all together, it means that the delayed expression § A means dereference the 
current reference address and use it recursively as the next base address. This 
continues until the chain of addresses ends. 

Hie Useful Part: Function Names 

The right-hand column of the Stack Crawl window contains the most useful tidbits 
of information: the names of functions (with the most recently called function listed 
first). Each function name is given symbolically; the hex number listed to the right 
is the offset of the return address based from the beginning of the function. Usually, 
however, the symbolic context is all that is needed—unless there are multiple calls 
to the same function from a calling function. 

Stack Crawl Window Preferences 

The window preferences of the Stack Crawl window are exactly the same as those 
of the Memory window. This is no surprise since a Stack Crawl window is simply a 
special case of a Memory window. 
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Memory Windows in General 

The Stack Crawl window is a Memory window with more of the optional fields 
defined. You can invent your own types (see Chapter 7 of the Tutorial, Templates or 
Section 5.5 of the Technical Reference ) and define your own Memory window. It is a 
simple matter to put an AddMenu command into the TMON Settings file—making 
the command appear in the TMON menu. 45 

An example you may find useful is: 

AddMenu 100,"WindowNames'', "new Memory StringHandle, AWindowList A +86 A(S+$A) A 
?? A(§+$A) A +$86" ^ ' 

This shows the names of the windows in the current window list. It uses the offset 
in a WindowRecord to the window’s titleHandle and the nextWindow pointer. It is 
left as an exercise to the reader to understand exactly how this works. 


Heap Lore 

Normal high-level languages like Pascal and C have traditionally used heaps for 
storage. For years, function calls (e.g., new and dispose) have been used in 
Pascal programs, as well as with various kinds of alloc functions for C programs. 
Although the Macintosh environment needs a unique cadre of functions to support 
iMacintosh heap operations, the firmament is the same: store an application’s things 
in RAM for unknown periods of time. 


What’s In a Heap 

A reasonable” amount of RAM is allocated for an application’s heap when a 
program is started. The single contiguous heap forms one large block, marked 
free. The free parts of the heap are whittled down as a program requests to use its 
heap space. Memory space is shuffled and reused when the available free blocks 
become too small to fulfill an immediate need. At times, larger used blocks marked 
“purgeable” are reclaimed; but in normal circumstances, the used blocks marked 
“relocatable” are moved around so that several of the small free blocks may be 
grouped together to make a bigger one. 

Block Header 

Each block of heap, starts with an eight- or twelve-byte header, depending on 
whether 24 or 32-bit system software is running. This header information tells 
whether the block is free, relocatable, or nonrelocatable. It also indicates the size of 
the block and the size of its correction value. In addition, it has a four-byte value 
that contains either 1) absolutely no useful information (in the case of a free block), 
2) a handle to the master pointer of a relocatable block or 3) a pointer to the 
beginning of the heap—in the case of a nonrelocatable block. For more details, 
please refer to the Memory Manager chapter of Inside Macintosh. 
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Heap Block Contents 

A heap’s contents of blocks range from single byte values (used directly by 
application code) to thousands of bytes (of resources). Using any information 
accessible through the system, TMON makes every attempt to display the contents 
of these blocks. Some of the block types are fcbs— which contains all the file 
control blocks; GrayRgn —the rounded region which defines the desktop, and 
UnitTable —which contains all device control blocks. The Technical Reference 
lists a number of the block types that can appear in the Heap window. 

The components of WMgrPort are identified by a phrase beginning with WMgrPort 
followed by a message. Meanwhile, all windows in the window list are identified by 
a phrase beginning with Window @$ followed by a message. Below is a list of 
messages and their respective descriptions. 


Message _ Description 


VisRgn 

The visible region of a window 

ClipRgn 

The clipping region 

PicSave 

Data for picture being saved 

RgnSave 

Data for region being saved 

PolySave 

Data for polygon being saved 

StrucRgn 

Structure region of window 

CntRgn 

Content region of window 

Update REgn 

Update region of window 

WData 

Window-defined data 

WTitle 

The title string 

WPic 

Picture used to update window 

DlgltemList 

Dialog window item list 

TEHandle 

Dialog window TextEdit record 

Item #$.. type $ 

Dialog window DlgltemList item 

The first number is the item number 
(starting from 0); the second number is 
the item type 

Control 

Any control belonging to a window 

This is displayed only if the control 
could not be identified as an item in 
that window’s DlgltemList 
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Heap Window 


Opening a Heap window in the usual way (pressing 3€-h or selecting Heap in the 
control menu) initially lists all known heaps by owner. TMON may not know of 
every heap at that point, but it can be taught. 


Heap Address Range System and Multifinder HeaDs 

Type Creator 

Preference Box 


LJ neap x 

*00002000..*001FI643 
*001F1644..*00718407 
az *00306700..*0060165F 
*00607708..*00702463 
♦007007E0..$00700807 

System f \ 
flu It i Finder \ 

SaveScreen \ 

Finder \ 

#*0008 'APPL' '????' 
#*0002 'FNDR' 'MACS' 
#*0001 'ZSYS* 'MACS' 

\ 

'ET 

■f 

± 

* 


Foreground and Background 

Task Unique 




Application Tasks Identifier Number 


Figure 5.20 Heap Window - Heap List 

Double-clicking on one of the heaps in the list will display that heap. In the top line 
displaySea^ 0 ^ tyPmg “ addreSS included within a known heap will also 

Note the lowercaseletters to the left of the application “SaveScreen” in the heap 

Inn^nTi 3 ^' P 16 lette f a L marks which hea P zone is *e current application 
one. The letter z means that the heap zone is the current zone, a.k.a.,the zone in 

The Zone. Damaged heap zones are marked with a solid-filled diamond (‘V — 
Chicago fonts Option-Control-S). 

TMON recognizes a new heap if you type the heap’s address in the field Custom 
Heap Zone, which lives among the Heap window preferences. 

J?AW in L° f th ^u He u P win j? w has hvo components: 1) the heap address and 2) 
the block address. The heap address specifies an address that falls anywhere within 
a valid heap. The block address is the address of the first block in the window 
invalid blocks are marked by a solid-filled diamond (“♦’) in the left column 
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Heap Base Address (Heap-Expr) 

Address Range / Address of First Item in Window (Block-Addr) 
of This Heap j I Decimal Size of Heap in File System Blocks 


□ MadAu II 1.1 
*00214388?.S082EA8F4 
*00040240 free, *000060* 

• S002565C0 00001CAA 2 

*00258274 00000D78 6 

• *00258FF4 000004B0 0 

*602594AC 00600460 0 

*00259964 08000000 4 

*00259970 0000000C 0 

*00259984 00000800 4 

*00259998 08000002 2 
*6025999C 00080048 6 
*002S99EC 00080143 3 
I2S9B40 l 

I259B54 < 

*00258364 I 

*00261564 I 

*86269824 ( 

*00269860 0008001C I 

*00269E90 00080016 2 

*00269EB8 000000IE 2 
*00269ED8 00600118 0 

*00269FF8 00800002 2 

*00260004 00000002 2 

*00260010 000000F0 0 

*00260168 000080F6 2 

*00260208 000800B1 3 

*60260204 000000BB 1 

*00260388 00008059 3 

*002603£C 000000AE 2 




.500 



*00268500 008002CA 2 

*08260894 00080009 3 

i*0026A8A8 00000700 0 

*06268080 


| Block Address 

Size ot Block 
Nonrelocatable Block 


*214301 
199 block 
l purgeable. *8007E308 

Handle**002143F8 «LpR. 

Handle-*002143F4 «LpR. 

Nonrelocatable 
Nonrelocatable 
Handle«*002593CC «lpr. 
Handler*6825986C «lpr. 
Handle*=*002598C8 «lpr. 
Handle*=*032598EC <1PR. 
Hand1***08259484 «lpr. 
Handle**30253410 «lpr. 
Free 

Handl«**00214438 <lpr. 
Handle-*0025949C «lpr. 
Handle=*00259498 «lpr. 
Hand1e**002S94S4 «lpr. 
Hand 1 ©'=*00259490 <lpr. 
Handl©**00259480 «lpr. 
Handle-*00259488 «lpr. 
Hand1e**0025S424 «lpr. 
Hand1e**00259418 «lpr. 
Handl©'*08259420 «lpr. 
Handl***00259400 <lpr. 

Handle=*002593FC «lpr. 

Handle=*002593F4 «lpr. 
Handle-*002593F0 «lpr. 
Handle**002593EC «lpr. 

Handle-*002593E8 «lpr. 

Handle-*80259404 «lpr. 
Handl©*=*00259480 «lpr. 
Handle**002593E0 «1PR. 
Handle**002S946C «1PR. 
Handle**002S94A0 «lpr. 
Handle**802S93£4 <lpr. 


used; *00040236 maxBlock, 

'COO£‘C*0011/*®30E 

_» 'CODE'6*0312/*03A£ 


.» *STR '«*0153/*03AI 


Handle Flags 
■» (Capital Means True) 

*/ 


•* Resource Number 

•J Resource / 

:» Type / 

'ST^#‘6*010*li*c: 

.» *str# , 6*61a8/*03ae 



maxPurgeBlock 


Resource Blocks 



Locked Bit\ Is a Resource Bit File Number 
is Purgeable Bit 
Handle I o Relocatable Block 


Number of Unused Bytes at End of Block 


Figure 5.21 Heap Window Block List 
Heap Window Preferences 

There are three unique options for a Heap window. The first option permits you to 
set the Custom Heap Zone. The second option, scrambling the heap, forces 
relocatable blocks in heap to be moved around to uncover for out-of-date handles. 
This requires placing the text cursor after the Scramble Now: and pressing 
Return or Enter (or pressing Control-S whenever this is the active window). 
The third option purges handles in the currently visible heap. 

The other two hidden options, Capture and Print, work as other TMON window 
Capture and Print options—they are turned on and off using the Printing 
window, placing the cursor next to Print or Capture and pressing Return. 


Define a Custom Heap Zone Eliminate Purgeable Handles 


□ Heap \ 

Custom heap zone! 0 

Scramble now; Purge now: 

Capture V 

Print \ 



♦ 

± 

*00802000. .^01F1643 Susie" 

*001F1644..*80718407 MultiFinder 
az *003AB7O0..*8060165F SaveScreen 
*00687708..*00>024E3 Finder 
*0078B7E8..*087K»0C7 Back grounder 

#*880C 'ftPPL' •????' 

#*0002 *FNDR 1 'MACS' 

#*0001 '2SYS' 'MACS' 


S3 

\ 



s 


Move Relocatable Blocks Around in Heap 


Figure 5.22 Heap Window Hidden Options 

Special note: There are heap options made available in the Options window 
(described next) that can be turned off. If these options are off, then heap 
information will be invisible when a Heap window is opened. 
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Options Window 

Options is a catch-all window for adjusting a few things in TMON. The Options 
window appears on the screen in the usual way (r Meeting the Options menu item) 
or by pressing -Option-O (as in Oscar). The major categories handled are: 

Screen Features 
Color Table 
Labels (and Addresses) 

Heartbeat 

Exiting 

Safety Options 


In Case System Has Multiple Screens _ TMON Pro RAM Usage _No Preferences Bpx 


as Mult 

y- 


t 


Cl Options 
[Monitor memory: 


. 189K free, / .8K purgeable. 


variable data, .143K fixed data; .704K total. 


Use screen X Cl available)' 

[Maximum width .640 Maximum height ,16384 Maximum depth .32. 
®Save background SUse alternate screen pagi- 


UOecrease screen depth when low on memory ^__ 
DShow-through background DShou-through W dWVerent depth^ 


jChanging screen dimensions may close all Monitor windows. 


^Window Dimensions and Depth 
=■ Window Memory Usage 
■— Window Appearance 


- Color Table ■ 


Depth 

.1 


Black Even gray Odd gray Highlight 


*0 

*F9 

*30EF 


*F9 

♦4210 


.32 *00FFFFFF *00000000 *007F7F7F *00808080 S80FFFFFF 



Editable Color Bit Patterns 


— Exiting • 


®Break on .Debugger and .DebugStr traps 
□ Only act on traps below interrupt level: 1 
□Only trace below interrupt level: 1 
1]Ignore intercepts and signals for the next instruction 


®Warn on exception vector changes 


Warnings, VBL Activation, Tracing, 
Monitor Activation 
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Screen Section 

The screen options adjust the graphical appearance of any TMON windows. By 
default, TMON windows occupy the entire width of the display when created. Also 
by default, TMON uses Screen #1 for displaying its menu and windows. 

Which Screen To Use? 

The first option— Use Screen— permits you to change the screen used: simply 
place the edit cursor after the word screen, type the screen number, and press 
Return (or Enter). The screen numbers coincide with the numbers associated 
with each display by the Monitors control panel device. 

Width and Height 

To change the width of all TMON windows, place the edit cursor after Maximum 
Width, and enter the new number. All TMON windows will be closed, and the 
TMON menu will be displayed using the new maximum width. 

The maximum height can be similarly adjusted. The maximum depth can be 
specified, in case you are showing TMON windows using a color display with a 
depth of 32-bits per pixel; this number can be made smaller to save memory space. 

Retaining the Background Screen Image When TMON is 
Active 

The Save Background option is normally turned on to maintain the contents of 
the screen as it was before the TMON monitor kicked in. Deselecting the option 
saves memory space, but may cause some consternation because application 
windows won’t be properly updated since most applications won’t know that TMON 
has been through to erase their part of the screen, 

By default, the option Use Alternative Screen Pages is turned on, because 
this speeds the operation of TMON. Leaving it on saves some memory space. 

Screen Depth 

The option to Decrease screen depth when low on memory is active by 
default. It reduces the space needed in TMON’s heap to save the current user 
screen. This is done in case there isn’t enough space available to save the whole 
thing. This will not be done if the checkbox is not selected. 

Show-Through 

The Show-through background option controls the display of application 
windows within the area occupied by TMON windows during the time the monitor 
actively uses the screen. 


Color Table Section 

The color table values offered by the Options window are editable: you can change 
the effective values of each of the colors for each of the provided bit depths. 
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Although the bit depth of 1 does not have enough information per pixel to discern 
the difference beyond black and white; other variations are still available, because 
they require some form of representation. 

Section 7.3.9 of the Technical Reference describes a way to get out of the situation 
where all the colors are set to the same value. 

Labels Section 

The labels section is filled with all kinds of checkboxes. By default, all of them are 
checked. 

The first group controls the location of searches for viable label information (heaps, 
resources, and MultiFinder worlds). The two C++ options, Unmangle C++ 
labels and Short C++ labels, will make sense only if you are using or are 
influenced strongly by C++. By default, these are turned on (developmental trends 
indicate this direction). 

NOTE: TMON is written primarily in C++. 

The second group in this section controls the listing of labels within TMON 
windows. The master switch checkbox on the left either shows or hides all of the 
labels. Note that Memory windows are no longer intelligent when labels are 
deselected (either individually or by the master switch). 

Monitor Heartbeat 

TMON watches the system ticks carefully to determine the time for its periodic 
check. For example, two of the items/events that are checked are stack-and-heap 
collisions and the allocation of new blocks into heap zones. Reducing the heartbeat 
value from the default of 300 ticks to a lower number will improve TMON Pro’s 
watchfulness, but possibly at a performance cost. Reducing the heartbeat value does 
not noticeably affect software attempting to perform tasks in real time. But, 
increasing the number may reduce TMON’s effectiveness in reacting to system 
changes. 

Exiting 

There may be times when you have been debugging a program for hours and have 
installed a gi-zillion calls to the _Debugger trap in your code. But, what you’d 
really like to do is just watch the program run uninterrupted for an extended length 
of time without having the breaks slam on and have the TMON monitor appear. 
The first option Break on _Debugger trap permits you to turn the break 
feature off. 

The next four options are self-explanatory. Option One: “Only act on traps below 
interrupt level: n” allows you to restrict TMON’s trap actions (e.g. recording and 
intercepting) to lower interrupt priorities. Option Two: “Only trace below interrupt 
level: n” causes the monitor to stop tracing instructions whenever the interrupt 
level is equal to or greater than the specified threshold. Option Three: Turning off 
VBL tasks automatically can be a bad idea, so a switch for the option is provided. 
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Option Four: News that exception vectors have been modified may become 
redundant, so you can turn off the warnings. 

Safety Options 

The safety options allow parts of TMON to be turned off. Generally, these parts of 
TMON depend upon portions of the Macintosh OS (such as the File Manager) to 
be alive and healthy. By default, these are left on, so TMON can offer full 
functionality. See Section 7.3.9 of the Technical Reference for more information. 


Other Useful Utility Windows 

Two utility windows haven’t been mentioned yet: 1) Search windows and 2) 
Compare windows. A Search window is used to look from one point in memory to 
another point in memory for values. A Compare window lists the differences 
between those two sections of memory. 

Searching Memory 

A search can be made by calling up a Search window—either by 1) selecting the 
Search menu item or 2) typing K-Option-F. Searching memory for strings, 
datums (long hex values like $48E730202F2DFE) or integers has only a couple of 
twists. Specifying a range and a value to search for is easy. For example: 

0..FFFFFF, "Apple" 

The top line of the example searches for all instances of the string “Apple” in 
memory between addresses $0 to $FFFFFF, inclusive. Twist number one involves 
alignment. Using the Byte, Word, and Long preferences, you can indicate the 
alignment of items along byte boundaries (that is, everything qualifies); word 
boundaries—where items must start at even addresses only; or long boundaries— 
where items must start at addresses multiples of 4:0,4,8, $C, etc... 

Twist number two involves values. For strange offsets, value-specific searches can 
be made by using the Phase option. Phase=0 means that no offset should be used. 
Phase=l means find items that start one byte out of phase. When searching for 
longs, this means a qualified value must start at addresses 1,5,9, $D, etc... 

As with other TMON commands, a search can be performed by typing the long 
form of a search command in a Command window (the keyword Search must be 
included). A Command window can be created by typing space (the window 
will appear at the bottom of the screen). 

Using the top line of the Search window or within a Command window, each of the 
hidden options can be typed in as a preference. Preferences can be optionally typed 
in the top line first, followed by the search range and search value. For example: 

/Maxlines=256, /User, /Byte, /Phase=0, $3000.. $30000, .1024 
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The command above searches for the decimal value 1024 using several default 
preferences. The Technical Reference lists all the preferences for Search windows in 
Section 7.1.8, providing details on the script form of the Search command. 
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Most preferences for the Compare window involve the kind of address space in 
which the comparison will take place. These options can be selected by 1) using the 
mouse or 2) typing them in as compare command preferences: 

/Physical, 0..ffff, 30000 

If the above example is typed in at the top line of the Compare window, a 
comparison will be performed between the 64K bytes of the first block starting at 
address 0 and the second block starting at $30000. The following would have to be 
typed in a Command window in order to perform the same task: 

New Compare /Physical, 0..ffff, 30000 

When the Compare window provides a listing, the items in the listing are where 
mismatches occur. The first and second ranges are where mismatches occur in the 
respective blocks. The data that follows are the first mismatching values from each 
range for each block at the indicated addresses. Only the first few mismatching 
bytes of any given range are listed due to space considerations. 

As with the Search window, you can use Option-click to view the mismatches 
in detail. Do this by creating a Dump, Assembler, or Memory window and setting 
the base address to AO. 


Summary 

This is the largest chapter in the TMON Tutorial. We’ve basically looked at 
memory data: how it can be viewed and how it can be found. To quickly identify 
data, it is often labelled. So, we looked atTMON’s labeling system. We investigated 
TMON’s different types of windows: Dump, Memory, Registers, Options, Search, 
and Compare windows. Within that discussion, we talked about expressions and the 
tools used in looking at the stack and heap. 
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There are two easily identified areas of interest in Macintosh files: 1) the resource 
fork and 2) the data fork. 

To explore the data forks of disk files, TMON provides the View window. Since it is 
one of the few TMON facilities that relies upon standard Macintosh OS code, 
TMON will turn it off as conditions warrant. (The Options window provides a 
checkbox for this purpose.) 

To explore the resource fork of disk files, TMON provides the File window. This 
window displays a list of resources contained within an open resource file. Because 
the File window does not use the Macintosh OS code—as the View window does— 
it cannot know which files aren’t loaded into RAM. This means that the resource list 
for an unlaunched program cannot be seen. Other windows are used to display the 
contents of resources while they’re in RAM. 

Each of the TMON windows described in this chapter can be controlled using 
specified key combinations (e.g., Control-Tab), mouse selections (e.g., selecting 
checkboxes) or typing the commands in scripts or in a Command window. 
Coverage of command scripts, and the full command language starts in the next 
chapter of the Tutorial and continues. 


Inspecting Data Forks 

The view window is used to display the contents of a disk file’s data fork. When 
creating a View window (by selecting the view menu item), you should see 
something like this: 


P^th Name 

vRefNym 

D/ive Number 



□ Oieu 
"Tzadkiel:" 

_\_ 

\ 

SFFFF 

/ 

♦0005 

□ 

n 

5 

ISI 


Volume Name 


Figure 6.1 View Window Volume List 

When choosing a file, the View window first shows the current list of available 
volumes. Picking a volume shows you its highest list of files and directories. Go 
through the directories until you find a file you like by double clicking it. 
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File Type File Creator Length Fork 

X Directory/ / / 

Directory/ I / 


Data 

Fork 

Le/igth 


Resource File or 
Fork Length Directory ID 


Preferences 

Box 




□ View "Tzadkiei:" 
'Apps" 

'OAs" 

'Oesktop" 

'Fonts'* 

'MacDrau II 1.1" 

'MPW*' 

’Multifinder 6.0.5'' 
'MuItiFinder 6.1b9 n 
'NO EXECUTE /" 
'Personal Data" 
'System Folder 6.0.5“ 
'Users” 


i Directory 
\Directory. 

’FNDR * 'ERIK 
Directory 
‘APPL‘ ’MDPL 
Directory 
Directory 
Directory 
Directory 
Directory 
Directory 
Directory 


$88800030 *08017505 
*00000026 *0807AE6A 


*00000132 

*00000101 


*000001E1 
*000004F0 
*000004F6 
*00000939 
*000004F3 


*00080131 
S000000A7 
*000001E6 


Figure 6.2 View Directory List 

The first column of the window contains file names exactly as they appear, with 
quotation marks setting off trailing spaces if any are present. The second column 
indicates the kind of entry it is: 1) a directory—a.k.a. folder or 2) a file. If it is a file, 
then the file type, file creator, data fork length, resource fork length, and file ID are 
shown. 

To go up or down in the file system with the View window, just edit the path shown 
on the top line. To climb up a level, change the path HardDisktSystem Folder: into 
HardDisk:. This can be done two ways: a hard way and an easy way. The hard way 
is by placing the edit cursor after the second colon, pressing backspace until the 
appropriate characters have been removed, then pressing Return. The easy way is 
by pressing 3€-t to go up one folder at a time. 

To go down and display the contents of a subdirectory, either add the name of the 
directory to the current path or double-click over the directory’s entry in the View 
list. 

To set up for the next trick, use the View window to look at the TMON folder within 
your system folder. You may see a display like the following files listed below: 



6.0.5:TMON Folder:" 

□ 



•APPL' 'Tnon' *0000149F *000A9AC0 *000000F5 



"TMON Settings" 

•MSet* 'Tnon' *00000010 *00008786 *000000F6 






+ 




a 


Figure 6.3 Folder Containing TMON and TMON Settings Files 
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TMON itself has a .fascinating example of a data fork. Take a look at it. You should 
see something similar to the following: 


□ Uieu "BrittaniarSystem Folder: TMON Folder: TMON 1 *, ISSISK 
AddMenu *04082010, "Close "Close" S: "Close /All^ 

AddMenu *94082029, "Clone d*li*", "Clone" 

IE rlni Top "Print Image",S: "Print Image /All" 

A^ enU * 04003020 > Capture Top a$li»Y",s: "CaptureImage",S: "Capturelmaqe /All" 
AddMenu *04084810,"ShowScrn 0*11'",“UserScreendnWait* * 

Standard key equivalents 
;AddKey Msocr-W, "Close'* 

AddKey MSocr-W,“Close /All" 

AddKey MOcr-W,"Close /Ail" 

AddKey Msocr-Equa1,"C1 one" 

AddKey MsOcr-P,"PrintIwage" 

AddKey MSOcr-P,“PrintImage /All" 

AddKey MsOcr-Y,"Capturelmage" 

[AddKey MSOcr-Y,"Capturelnaoe /All" 

[AddKey Mocr—2,"Undo" 

AddKey Msocr-X,"Cut" 

AddKey MSoc-X,"Cut /Append" 

AddKey Msocr-C,"Copy" 

AddKey MSocr-C,"Copy /Append" 

AddKey Moc-U,"Paste" 

AddKey Msocr-Space,"New Command" 

AddKey MSocr-Space,"Last Command" 

AddKey Mocr-M,"Open Memory" 

[AddKey Mocr-D,"Open Dump" 

AddKey Mocr-A,"Open Assembly" 

AddKey Mocr-H,“Open Heap" 

AddKey Mocr—L,"Open File" 

AddKey Mocr-O,"Open View" 

AddKey Mocr-N,"Open Number" 

AddKey MOcr-N,"Open Uars" 

AddKey Mocr-I,"Open Identifiers" 

|AddKey Mocr-R,"Open Registers" 

!AddKey Mocr-F,"Open Find" 
iAddKey MOci—F, "Open Search" 

AddKey MOcr—M,"Open Compare" 

AddKey MOcr-C,"StackCrawl A6" 

AddKey Mocr 8,"Open Breakpoints" 

AddKey Ptocr-T, "Open Traps" 

AddKey MOcr—R,"Open Record" 

AddKey Mocr-P,"Open Printing" 

AddKey MOcr-O,“Open Options" 

AddKey Msocr-E,"Exit" 

AddKey MSocr E,"Exit /IntoSysErr" 


1#.48 □ 


Figure 6.4 Data Fork of TMON 

View Window Preferences 


Here is a View window with window preferences visible. There isn’t much to them. 
There is a decimal setting for the tab size in characters. The horizontal position is 
the horizontal offset position for the contents of the View window. The Dynamic 
Update box is selected if changes to the file are automatically reflected in the View 
window. The usual Capture and Print options are there, as is the Set Default 
box. 


; □ View "Scratch Disk:" 

Tab=». 4 Horizontal posit ion*.0 

Capture "Scratch Disk:" - 

iPrint "Scratch Disk:", 


®Oynamic update 


®Set Default 


± 

± 


"BootMan u/labels" 
"CMC Prefs" 

"Color" 

"DAs" 

"Desktop" 

"6U" 

"Mirror" 

"On Cue" 1 " 
“SaveScreen" 
"Todd's C Stuff" 
H VX TMON Scripts" 


'APPL' 

'Bman' 

*00000080 S000069A1 

*00000071 

’CMCtr' 

’CMCA' 

*00000000 *0000023E 

*00000024 


'CMCA' 

*00000000 *00051CSC 

*00000025 


•DMOV' 

*00000000 J8002A6A3 

*00000072 


'ERIK* 

*00000000 *90801EF2 



*&Vjz* 

*00000000 *00010937 

*00000074 

Directory 

*INIT* •MFIfr 

*00000000 *00005CED 

*00000048 

*00000076 



*00000000 *00003E10 

*00000050 

Directory 


*00000037 

Directory 


*00000063 



Figure 6.5 View Window Preferences 
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Caveats on View Usage 

View windows are provided by TMON, but through the Macintosh File Manager 
a rare use of the ROMs. This means that if conditions are sufficiently unstable or 
dangerous, TMON will not let you use the View windows. 


Keyboard Tricks for Moving Around in View Windows 

Press the up or down arrow keys to select a file or directory higher or lower in the 
current view list, respectively. To show the currently selected file or directory, 
press either Return or 36-1. To move up in the hierarchy, press COMMAND- 
UpArrow. 

Finding Strings in a File’s Data Fork 

To search for strings in open View windows, use a Find window. Only strings may 
be used. 


Line Where String Is Found 


Line Number at Top 


□ Uieu "Tzadkiel: 
AddMenu *01002010," 
AddMenu *61802020, 
AddMenu *01003010, 
AddMenu *01004010, 
AddMenu *01004020, 
AddMenu *01004030, 
AddMenu *01005010, 
AddMenu *01006010, 
AddMenu *01006020, 
AddMenu *01006030, 
AddMenu *81008020, 
AddMenu *02001010, 
AddMenu *02002010, 
AddMenu *02003010, 
AddMenu *02004010, 
AddMenu *02008810, 
AddMenu *03001010, 
AddMenu *03001020, 
AddMenu *03001030, 
AddMenu *03001040, 
AddMenu $63001050, 


Polder 6.0.-51TMOM Folder:TMON”, 

d*l 


;#.20 □ ± 


Hea& i>*l 1H“, "Open Heap" 

•File d*llL","Open File” 

"Oieu d*110","Open Uieu" 

"Nun £*1IN",“Open Nunber” 

"(Jar* "Open Uars" 

"Identifiers Will”,"Open Identifiers" 

"Regs d*11R","Open Registers" 

"Find i*lIF*,"Open Find" 

•'Search d*l 1»F","Open Search" 

“Conpare d*ll*M”,"Open Conpare” 

“Stack Crawl mi*C“, "StackCraul A6" 

"Brkpts d*lIB","Open Breakpoints" 

"Traps $*11T","Open Trap*" 

"Record d*lleR","Open Record" 

"Printing **UP","Oper> Printing* 

“Options d*l1*0","Open Options" 

"Exit’ <J*UE",so: "Exit". So: "Exit /•IntoSysErr“,sO:"MExit",SO:"MExit /IntoSysErr" 

■losut, Mns-.«oc:"6o»ub-.,oC:-Go,ub 
"Step d*1IS“,soc:"Step",soC:"Step /Leap",Soc:"Step /IntoSysErr ,SoC. Step /Leap,rlnt. 
"Trace a*ll»T M ,oc:"Trace",oC:"Trace 4.eap",0c:"MTrace",X:"MTrace /Leap_ 


□ Find "Heap" 

Search 


String 


Figure 6.6 Find Window in Action 

To open a Find window, select the Find menu item in the control menu or press 
3€-F. Note that a Find window normally appears at the bottom of the screen, not 
underneath a View window as shown. 

Find Window Preferences 

The few options provided for the Find window are Case sensitive, Token 
(search for entire words), Backwards search, Wrap-around search, and Global 
search. With global search, each data fork displayed by an open Find window will 
be scanned. 

Selecting any of the checkboxes activates the option for the next find operation. 
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□ Find "Heap" ---------_ 

□ Case sen sitive PToken QBackuards [gWrap [gGlobal __ @s&t De>fa ® t 


Figure 6.7 Find Window Preferences 

find options can also be made with the keyboard using 

Case sensitive search Control-S 

Search for words Control-T 

Search backwards Control-B 

Wrap-around search Control-W 
global search Control-G 

Script commands are described in Chapter 7 of the Tutorial, while Section 7.3.5 of 
the 1 echmcal Reference describes the typed command form of the Find command. 


Activating and deactivating 
the following key presses: 


Showing the Status of a File’s Resources 

The File window first shows a list of resource files in each application’s resource file 
chain. Double-click on a file to see its resource list. 


File Number File Name 


r~. -/- ■__ 

*0 40C 


□ 

1+] 

*0001 

.ROM 



*0002 

System 


T 

*0110 

4. Suitcase- II 



*0236 




*0108 




*017A 

Quick 0£X-1_4A 



*02F2 

Backgrounder 



*0001 

ROM 



*0002 

System 



*011C 

4. Suitcase- II 



*0236 




*0108 




*817A 

Quick 0EX—1.4A 



*03AE 

Desktop 



*0350 




*0001 

ROM 



*0002 

System 



*011C 




*0236 




*0108 

SaveScreen 



*0178 

QuickDEX—1.4A 


s 


Figure 6.8 File Window File List 


In a File window file list, you may notice some files listed more than once. 
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File Reference Number Number of Resources File Attributes 


File Map Location ^ 


□ System File *2 

~1 - 


’ □ 

* 

File *0082 Map at 

*£fc044AD4 

.343 resources attr 

butes=rcu. 


Tupe $ ID Attributes File offset Handle Ptr 

Name 


'DLOG'$*0282 

..P.. 

.. *00056440 

Not loaded 



'DRUR’$*0082 

1HP.. 

.. *00802540 

50033E4EC Purged 

“.Print* 


’DRUR’$*©073 

.HP.. 

.. 5000026EC 

*00010010 Purged 

",Disp1ay_Uideo_App1e_TF8" 


■DRUR'$*000F 

1HP. . 

.. S0080303E 

S8383E4E8 Purged 

"dBChooser" 


'DRUR'$*8012 

1HP. . 

.. 508005DA0 

50003E4E4 Purged 

“d0Control Panel" 


‘DRUR'$*0000 

1HP.. 

.. *03050707 

*0003E4E8 Purged 

"d0Access Privileges" 


'DRUR'$*0028 


.. *000526AA 

*08010020 Purged 

".XPP" 


-DRUR‘$*0029 

• HPL. 

.. *00053150 

50002E1A0 Purged 

AFPTranslator" 


’DRUR‘$*0000 

1HP.. 

.. *00853FA8 

50003E4DC Purged 

"d0Alarn Clock" 


*DRUR’ $*000E 

1 HP.. 

.. 500354FE8 

50003E4D8 Purged 

"d0Calculator" 


•DRUR’$*0014 

1HP.. 

.. *00055060 

S0003E4D4 Puroed 

“d0Find File" 


•DRUR'$*0810 

1HP.. 

.. *08058152 

S0003E4D0 Purged 

"d0Key Caps" 


’DRUR’$*0011 

1HP. . 

.. 500858AF4 

*8003E4CC Purged 

"00Scrapbook" 


'DSAT’ $*0003 

. H.L. 

.. *00007402 

Not loaded 



'DSAT'$50802 

. H. L. 

.. *00007684 

Not loaded 



'FKEY' $*0003 

..P.. 

.. *00808158 

Not 1oaded 



’FKEY’ $*0604 

. .P.. 

.. *80008382 

Not loaded 



•FONT’$*0000 

.H... 

.. *00008414 

*0003E480 Purged 



•FONT‘$*0080 

1 HP. . 

.. *000esi4C 

50003E47C Purged 

"Chicago" 


•FONT’c^eies 

1 HP. . 

.. *00009190 

50003E478 Purged 



‘FONT' $*018C 

1 HP. . 

.. 5000099FC 

S0003E474 Purged 



•FONT'$*8180 

1HP.. 

.. 50000646E 

J0003E470 Purged 

"Geneva* 


'FONT’$*0209 

1HP.. 

.. *00006452 

J0033E46C Purged 



’FONT’ $*820C 

1HP.. 

.. 500006E5A 

J0003E468 Purged 



'FONT’$*0200 

1HP.. 

.. 50000B7FE 

50003E464 Purged 

"Monaco" 


1 FONT'$S0B09 

1HP.. 

.. 50005652A 

50003E460 Purged 



'FONT' $*0B0A 

1HP.. 

.. *0885AF8C 

500B3E45C Purged 



'FONT'$*0B0C 

1HP.. 

.. 50085B95E 

50003E458 Purged 



■FONT‘$*0B0E 

1HP. . 

.. *00050480 

50003E454 Purged 



'FONT'$*0B12 

1HP. . 

.. 50005D1FE 

S0003E450 Purged 



'FONT’$*0B18 

1HP. . 

.. 58005E47C 

50003E44C Purged 



’FONT' $*0B80 

1HP. . 

.. *08060086 

50003E448 Purged 

"Courier" 


'F ONT'$*018A 

1HP.. 

.. *00060990 

J0003E444 Purged 



•FONT'$*018E 

1HP.. 

.. *000613E6 

50003E440 Purged 



'FONT*$*0192 

1HP.. 

.. *00062IDA 

50003E43C Purged 



•FONT'$*0134 

1HP-. 

.. *000634DE 

50003E438 Purged 



■FONT’$*0198 

1 HP.. 

.. *00064BBA 

58083E434 Purged 



‘FONT’$*0A89 

1HP.. 

.. *00066982 

50003E430 Purged 



'FONT'$*0A8A 

1HP.. 

.. *00067430 

*0003E42C Purged 



'FONT’$*0A8C 

1HP. . 

.. *08067086 

50003E428 Purged 


SI 


Figure 6.9 File Window Resource List 

This does not mean that there is more than one copy of the file currently in 
memory. 

The File List portion of the File window isn’t capable of editing what you see. It is 
only informational. 


File Window Preferences 

The window preferences for the File window are shown below. The functional 
preferences are the standard capabilities for capturing to a TMON window and 
printing to a text file on disk. The informational preferences simply show what the 
letters mean for the file and resource attribute flag fields. The bit in the field 
corresponding to a lowercase letter is set to 0, while the bit in the field 
corresponding to an uppercase letter is set to 1. 


File Attribute Flag Legend Resource Attribute Flag Legend 

0 System File *2 ~ ' / / 

Capture *2 / / 

(Print *2 / I 

(File: Reread only C®compaci Unchanged / 

Resource: H»sys heap P»purgeable L 3 locked T=protected 5=preload Unchanged 

[File *0082 Map at *00044004 .343 resources attributes-rcw. 

Type 0 ID Attributes File offset Handle Ptr Name 

OL06'$*0282 ..P. *00050440 Not loaded 

DRUR'0*0002 1HP. *80002540 *0003E4EC Purged “.Print" 

DRUR'$*0078 .HP..... S000026EC *00010010 Purged Display_Uideo_Appl»_TFB" 

ORUR*$*000F 1HP. *0000303E 50003E4E8 Purged "^Chooser" 

DRUR'$*0812 1HP. *00005000 S8003E4E4 Purged “decontrol Panel" 

rttWJR‘«00AC 1 HP. «WV)WV707 SWtfTlFdFA Purnm-t 



Figure 6.10 File Window Preferences 


TMON Professional Tutorial 


105 













































Chapter 6. Exploring Memory 

Summary 

TMON provides two windows for inspecting disk files: 1) the View window for 
investigating data forks and 2) the File window for investigating resource forks. 

Investigating data forks is a simple matter with View windows. But at times, using 
the windows can be dangerous. This is because TMON uses the Macintosh ROMs 
for accessing disk-based fdes. Developers using TMON are more likely to 
encounter a major problem due to unstable application code. TMON watches for 
these conditions, and disables the View windows accordingly. 

Investigating resource forks is made possible with File windows. These show a 
program’s list of resources, including the program’s current status. This way, you 
can see improperly purged resources and their attributes. 

Up to this point we have been emphasizing the interactive parts of TMON. The 
following chapter emphasizes scripting capabilities, discussing all the commands 
provided by TMON. 
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TMON Professional provides an interactive debugging language with standard 
control structures such as IF—ELSE-END, WHILE-END, and BREAK. A number of 
useful commands are included. In addition, a number of arcane and rarely-used 
commands will be found; these are clearly labelled in the descriptions in this and 
other chapters. 

The following table contains all the currently existing TMON commands: 


AddError 

AddKey 

AddLabel 

AddMenu 

Alert 

Alias 

Assembly (Window) 

BREAK 

Breakpoints (Window) 

Capture (Prefix) 

Capturelmage 

Clear 

Clone 

Close 

Command (Window) 

Compare (Window) 

Copy 

Cut 

Default (Prefix) 

DeleteError 

DeleteKey 

DeleteMenu 

Discipline 

Dump (Window) 

ELSE 

END 

Enter 

Error 

Eval 

Exit 

ExitToShell 

File (Window) 

Fill 

Find (Window) 

First (Prefix) 

Gosub 

Heap (Window) 

Help (Prefix) 

Home 

Identifiers (Window) 

IF 

Include 

Insert 

Last (Prefix) 

LoadResource 

Macro 

MagicAddress 

MagicReturn 

Map 

Memory (Window) 

MonitorScreen 

MouseUnfreeze 

Move 

New (Prefix) 

Number (Window) 

Open (Prefix) 

Options (Window) 

Paste 

Print (Prefix) 

Printlmage 

Printing (Window) 

Purge 

Reboot 

Record (Window) 

Registers (Window) 

Scramble 

Search (Window) 

SelectAll 

ShutDown 

Step 

Trace 

Traps (Window) 

TRY 

Undo 

UserScreen 

Vars (Window) 

View (Window) 

Wait 


WHILE 

Except for a few commands, all of those listed above are detailed within this 
chapter. Some commands requiring more discussion (e.g., Step and Trace) are 
covered in Chapter 8, since they are used for breakpoints, traps, and stepping 
through assembly code. 

The commands that are marked by (Window) are introduced in various Tutorial 
chapters in their interactive form. Their script command forms are discussed at 
length in the Technical Reference. 

The (Prefix) commands work in conjunction with another command. For example, 
New Heap will create a Heap window. 

The command sequence used for creating the table above is as follows: 1) enter 
TMON, 2) open an Identifiers window, 3) select the window preferences button, 4) 
select the Clear Enables button, 5) select the Commands button, 6) type ... 


TMON Professional Tutorial 


107 


Chapter 7. Scripting for Fun and Profit 


Return in the top line, 7) print the contents of the Identifier window to a disk file_ 

using the Printing window to set the file name and print options, and 8) placing the 
text cursor back in the Identifiers window at the end of the Printing line and 
pressing Return completes the process. 


Knowing Your Quotes 

When working with TMON commands it is important to understand how TMON 
treats the four types of quote characters: 

"string 11 , 'literal', “identifier”, ‘case-sensitive identifier’ 

Double quotes are used to hold string values. String values are used to hold 
filenames, TMON menu names, macro and alias expansion strings, et cetera. To 
illustrate: for a memory Search command, you can assign a string value as one 
parameter; then for another parameter, you can specify whether the search is case 
sensitive or not. 

Single quotes are used to hold character-defined literals such as 'CODE', 'DITL', 
'Jay', and 'ABCabc'. The first three literals have integer values of $434F4445,’ 
$4449544C, and $4A6179 respectively. These can be used as part of any integer 
expression. The last example, 'ABCabc' is a datum—a sequence of 5 or more bytes. 
This has a value of $414243616263. Although datums cannot be used in integer 
expressions, they are useful for holding values for TMON’s use (e.g., as an 
argument to a memory Fill command). 

Identifiers are sequences of characters. They can be names of procedures and 
functions in memory, low memory global names, TMON commands, dcmds, 
aliases, an so on. Identifiers use typographic double quotation marks or typographic 
single quotation marks to enforce case sensitivity. Fortunately, TMON is very 
lenient and usually does not require you to enter the quotation marks. For example, 
you can open an Assembly window to the routine SetLight, without needing to type 
“SetLight”. However, if you have a routine in memory called ‘SetLight’ and another 
routine called ‘SETLIGHT’, you would would not have full control over which 
routine you are requesting TMON to view. This is true, unless you use the single 
typographic quotes. 

Quotation marks are discussed in more detail in Sections 5.2.4, 5.2.6, and 5.2.7 of 
the Technical Reference. Case-sensitive matching is discussed in Section 5.3.1 of the 
Technical Reference. 


Using a Command Window 

The Command window is used for entering TMON script command text. Pressing 
96 -Space causes a Command window to appear at the bottom of the display. (This 
window is easy to miss on large displays because it is only one line of text high.) 
TMON doesn t come with a menu entry for making a Command window, but 
adding one is easily done. Note the following command: 
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AddMenu $01008020, "Command 3$1ISpace”,"Open Command" 

Typing this command into a Command window and pressing Return will establish 
the menu item Command in the TMON control menu. That this item will be lost the 
next time the Macintosh is reset is a drawback for some and an advantage for 
others The AddMenu command can be made permanent by adding it to the 1 MON 
Settings script—which can be edited through the TMON Professional Loader 
dialog (described in Chapter 2 of this Tutorial). 


| □ Trace 0 _______________ 

Figure 7.1 Command Window 

Once you have a command window, you may enter any TMON command, alias, or 
dcmd extension. Pressing Shift-Return inserts a new line character, thus allowing 
multiple commands in a single Command window. 

Capture Windows are Fancy Command Windows 

Capture windows are Command windows that can be resized and scrolled. These 
can contain information captured from another window, dcmd, or other source. 
Information captured in a Capture window is not updated dynamically. 

Every time you want to create a new Command window, just press 3£-Space. To 
rotate through existing Command and Capture windows, press Shift-36-Space. 
The use of the Shift key is intentionally reversed from normal use. This is because 
command windows are often useful for storing command output, but can be reused 
easily. So, if you hit 36-Space, you will bring up a new window instead of using an 
existing one. This key combination prevents you from accidentally destroying the 
output of an existing capture window. 

You can reuse a command window in a manner similar to that of a dump window 
by changing the contents of the top line. If you have installed dcmds which output 
information, you can type a dcmd name and see the results output (captured) to the 
same window; then, type another dcmd name (the current selection is the top 
window command line) and reuse the window. This reduces window clutter. Hitting 
31 -space, will bring up a new window if you want to keep the old window. 

Below are some examples of capture windows from a command line: 

Capture Dump /word,800..900 

Capture Identifiers /clear,/A000=1,...font... 


Help 

Dcmds can support a Help prefix. Typing Help dcmdName on a command line 
will capture the dcmd help output to the same window just as the dcmd output 
normally does. If you are using the dcmds supplied with TMON, type 36-Space to 
bring up a command window. After this, type Help drvr to get help information 
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^ndow drVI " dCmd ’ Finally ’ 171)6 drvr t0 cal1 the dcmd ’ reusin g the same command 

Control Structures 


Contro 1 structures are used to construct meaningful scripts which can be stored in 
hies, loaded, and used later. Individual or groups of commands can be conditionally 
executed or executed repeatedly. TMON control structures—with one exception— 
go back to those of C and extended Pascal. The control structures are represented 
m th f e _ Comma n ds Table above as command (this is how they are presented in an 
Identifiers window), but they serve as control structures. 


IF/ELSE/END 

The IF /E LS E/EN D control structure contains no surprises. If the expression Booll 
in the expression 

if Booll 
Commandl 

END 


is nonzero (true), then the script commands Commandl are evaluated. The IF 
clause, the command (s), and the END must be on separate lines, or delimited by 
newline characters. The expression Booll must evaluate to an integer the IF 
command must have an END, and IF commands can be nested. Finally, you can 
pnmde a final ELSE clause containing commands to evaluate when everything else 
has failed. Another example: K 


if Booll 
Commandl 
ELSE IF Bool2 
Command2 

ELSE 

Command3 

END 


Those command components that must be on separate lines are shown as such. 


WHILE/END 


^ * oll °wing while/end command, Commandl will continue to be evaluated 
while Booll evaluates to a nonzero value. It is also possible to escape from the 
inside of the loop with a break command. 


WHILE Booll 
Commandl 

END 


While commands can be nested. 
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BREAK 

A BREAK command will escape from the inside of a WHILE/END loop. There are 
two forms of the break command: unconditional and conditional. The 
unconditional form is the unadorned appearance of the word break. The 
conditional form is the following: 

BREAK IF Booll 

The Booll expression is evaluated; if it is nonzero, then a break will be performed. 

TRY/END 

A TRY/END command is wrapped around script commands that need to be 
evaluated even under most error conditions. Even so, the TRY command cannot 
hold off a 3€-period or serious syntax errors. TRY comes in the following form: 

TRY 

Commandl 

END 

Include 

Here is the command you’ll use to load scripts from disk files. To have TMON go 
out and execute a script file, use the following: 

Include Filename 

where Filename is a string expression. A script file should contain complete script 
command expressions. For example, both ends of an IF command (the IF and the 
END) should be in one script file. Included files may include other files. 


Escape from the Depths 

The following script commands are used to get out of TMON, escape a bombed 
program, reset and shut down the machine, and escape from a subroutine. 

ExitToShell 

In many programmer’s mind, getting out of a wayward program is way up on the 
list of important things to know. The ExitToShell command is one way to do 
that: type it into the Command window, and the current application will be 
“terminated with extreme prejudice,” (as an operating system manual once said). 


Reboot 

There are three different ways to reboot the Macintosh: 
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1. Reboot is the command to reboot the Macintosh. This barest form of the 
command uses the Macintosh ShutDown Manager to perform a restart—this 
flushing and unmounting disk volumes. 

2. Reboot / Immediate instructs TMON to bypass the ShutDown manager. This 
simply resets the machine. 

3. Reboot /Unmount causes disk volumes to be flushed and unmounted, after 
which a reboot is performed as though the reset button were pressed. 

The middle option is technically more abrupt than either the first or last. 


ShutDown 


The ShutDown command uses the ShutDown Manager as if the Shut Down menu 
item were selected from the Special menu of the Finder. Disk volumes are flushed 
and unmounted by this process. There are no parameters to the ShutDown 
command. 


Exit 

The command Exit exits the TMON monitor and allow application code to 
proceed freely. It is executed by selecting the Exit menu item, or pressing 36-e. 

Several embellishments of this command exist: /SkipActions, /SkipBreak, 
/DoActions, and so on. (Sections 8.3.1, 8.3.2, and 8.3.3 of the Technical Reference 
provide a detailed discussion on the various options.) The form Exit /intoSysErr 
will cause a _SysError trap to execute if the current instruction says to do so. 
Normally, TMON intercepts SysError trap execution and becomes active, 
preventing the _SysError code from doing anything. Of course, this is no good if 
you happen to be debugging _SysError processing and have no recourse. 

Pressing Shift-SS-E has the same effect as Exit /IntoSysErr. Holding 
Shift down while selecting the Exit menu item has the same effect. 

Configuring Messages, Menus, Keys, 
Labels, and Maps 

The TMON scripting language provides a number of commands for adding and 
removing error messages, menu items, key equivalents, and labels. 

AddError 

It is easy to add new error messages to TMON using AddError. More details 
regarding the use of AddError can be found in the Technical Reference. Use of this 
command is expected to be rare. 
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In general, there are two kinds of error messages: system and TMON monitor. 
Each error message has an error number and a string. To create a system error 
message, the command has two forms: 

AddError number, string 


and 

AddError /System, number, string 

where number is an error number expression and string is any reasonable error 
message string. The command used to create a TMON monitor error message has 
one form: 

AddError /Monitor, number, string 


DeleteError 

If you can add error messages, you ought to be able to remove them. To remove a 
system error message, use DeleteError or DeleteError 

/System , number. To remove a TMON monitor error message, use 
DeleteError /Monitor number. 

Use of this command is expected to be rare. 


AddMenu 

A very popular command adds new menu items to TMON Pro’s menu. This 
command has the form: 

AddMenu refnum, string [, action }* 

where a number of alternate actions to take can be specified. The action to be 
executed depends upon the modifier keys that are pressed while the menu item is 
selected. An action has the form 

[modifiers :] action-string 

where the optional modifers are in the form of an upper or lower case letter. TMON 
watches five different modifier keys, also aware of repeating events under certain 
conditions. Holding the §§ key down, for example, is indicated by the presence of 
an upper case M within the modifiers string—lower case m if it isn’t pressed. These 
are all the modifier keys and their character equivalents in the modifiers string: 
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Key 

Letter 

& 

m M 

Shift 

s S 

Caps Lock 

1 L 

Option 

o O 

Control 

c C 

repeat 

r R 


The repeat modifier is a strange bird that monitors the time that a key is held down. 
The lower case ‘r’ stands for not holding the key down, while the upper case ‘R’ 
means holding the key down beyond the key repeat threshold time. This last case 
is said to match the repeat key invocation. The AddKey command, discussed 
shortly, also uses the repeat modifier for a different purpose: using the number of 
mouse click and the context of the mouse clicks for keying actions. Repeat is not 
allowed as a modifier for AddMenu. 

The following are AddMenu commands that were taken from TMON Pro’s data 
fork. Caution: check the current version of TMON for up-to-date versions of these 
commands. Blank lines have been added here to make reading easier. These are 
executed the by TMON upon start up: 

// Standard menu commands 

AddMenu $01001010,"Dump 9$llD”,"Open Dump" 

AddMenu $01001020,"Assembly 9$llA","Open Assembly" 

AddMenu $01001030, "Memory d$HM", "Open Memory" 

AddMenu $01002010,"Heap 9$llH","Open Heap" 

AddMenu $01002020,"File 9$11L","Open File” 

AddMenu $01003010,"View 9$110","Open View" 

AddMenu $01004010,"Num 9$llN","Open Number" 

AddMenu $01004020,"Vars 9$11•N", "Open Vars" 

AddMenu $01004030,"Identifiers 9$11I","Open Identifiers” 
AddMenu $01005010,"Regs 9$llR","Open Registers" 

AddMenu $01006010, "Find 9$llF","Open Find" 

AddMenu $01006020,"Search 9$11*F","Open Search" 

AddMenu $01006030,"Compare 9$11*M","Open Compare" 

AddMenu $01008010,"Stack Crawl 9$11*0","StackCrawl A6" 

AddMenu $02001010,"Brkpts 9$11B","Open Breakpoints" 

AddMenu $02002010,"Traps 9$11T", "Open Traps" 

AddMenu $02003010,"Record 9$11•R","Open Record" 

AddMenu $02004010, "Printing 9$llP”,”Open Printing" 

AddMenu $02008010,"Options 9$11’0","Open Options" 

AddMenu $03001010,"RTE","RTE” 

AddMenu $03001020,"Exit 9$11E”, so:"Exit",So:"Exit 
/IntoSysErr",sO:"MExit", SO:"MExit /IntoSysErr” 

AddMenu $03001030,"GoSub 9$11G",soc:"Gosub”,soC:"Gosub 
/Leap”, Soc: "Gosub /IntoSysErr", SoC: "Gosub /L... 

AddMenu $03001040,"Step 9$11S", soc:"Step",soC:"Step 
/Leap",Soc:"Step /IntoSysErr", SoC:"Step /Leap,/™ 
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AddMenu $03001050,"Trace 3$11*T",oc:"Trace”,oC:"Trace 
/Leap",Oc:"MTrace",OC:"MTrace /Leap" 

AddMenu $03002010,"PopA7",so:"PopA7",So:"PopA7 /IntoSysErr" 
AddMenu $03002020,"PopA6",so:"PopA6",So:"PopA6 /IntoSysErr" 
AddMenu $03003010,"ExitToShell 3$11^E","ExitToShell" 

AddMenu $04001010,"Undo 3$11Z","Undo" 

AddMenu $04001020,"Cut 3$11X",s:"Cut”,S:"Cut /Append" 

AddMenu $04001030,"Copy 3$11C",s:"Copy",S:"Copy /Append” 
AddMenu $04001040,"Paste 3$11V”,"Paste" 

AddMenu $04002010,"Close 3$11W",s:"Close",S:"Close /All" 
AddMenu $04002020,"Clone 3$11=","Clone" 

AddMenu $04003010,"Print Top 

3$11*P",s:"Printlmage”,S:"Printlmage /All" 

AddMenu $04003020,"Capture Top 

3$11•Y",s:"CaptureImage",S:"Capturelmage /All" 

AddMenu $04004010,"ShowScrn 3$11'","UserScreenSnWait" 

The first hexadecimal number in each command—the refnurn —indicates the menu 
item location in the TMON menu. There are some arcane rules that are used for 
menu item placement. First and easiest: menu items are shown in refnum order. 
Second: an extra space is inserted between items whose number differ in the first 
six hex digits. Third, a line break is inserted between items whose number differ in 
the first four hex digits. 

The hieroglyphs within nearly all of the menu item strings translate into the 
symbolic representation of the key equivalent. The 3 means “literal,” and the $11 
means the character corresponding to the hex value 11, which is the symbol for the 
36 key. 

DeleteMenu 

If you can add a menu item, you should be able to delete it. Menu items can be 
deleted either by reference number, by string or both using the following 
command: 

DeleteMenu 42,"String" 

DeleteMenu 42 
DeleteMenu ,"String" 

AddKey 

The AddKey command defines a new key equivalent for script commands and 
menu selections. A key equivalent is a combination of key presses in the form of a 
single regular key (e.g., X and zero or more modifier keys). 

Modifier keys are any of the keyboard keys that don’t normally do anything when 
pressed by themselves like Control and 36. Modifiers could also indicate the time 
a regular key is held down. All valid modifier keys are listed in a chart (above) 
within the description on the AddMenu command. 
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The AddKey command format is: 

AddKey [modifiers -] keyCode, action-string 

The modifiers field contains any of the valid modifier codes mentioned in in the 
modifier table: ‘o’ stands for Option key pressed, and so on. The keyCode is either 
the symbolic equivalent of a key (i.e. the V key has a keyCode of Period or 
PadPer iod) or a hexadecimal value (7 is also $2F or $41, depending on which key 
is pressed). Many of the valid keycodes are listed in the Technical Reference in 
Table 8.3. Note that the key mapping could change for international systems. 

Click keyCode and the § Symbol 

There is a special keyCode— Click —which allows a mouse click to be used as a 
key equivalent. TMON remembers the context of the mouse click so that the 
information can be used whenever the § symbol, the clicked value evaluator, is 
employed. 

For example, when the Click key code is used in the keyCode field, and the § 
symbol is used in the action-string field, the context (the evaluated value) of where 
the mouse click will be inserted within the action-string instead of the occurrence 
of §. Specifying the appropriate modifier key positions restricts the invocation of a 
modifier- Click key equivalent to that mouse click-modifier key combination. 

Here are some of the standard TMON-Pro definitions that use the option-click 
method for invoking actions: 

// Standard "option-click" actions 
AddKey msOcr-Click,"Number 0=§" 

AddKey msOcR-Click,"New Number 0=§" 

AddKey mSOcr-Click,"Number §" 

AddKey mSOcR-Click,"New Number §" 

AddKey Moc-Click,"New Memory :§" 

AddKey MOc-Click,"New Dump §" 

AddKey MoC-Click,"New Assembly §" 

AddKey MOC-Click,"Step PC==§" 

AddKey msoCr-Click,"Breakpoints set §:,0" 

AddKey msOCr-Click,"Breakpoints set §" 

AddKey msCR-Click,"Exit" 

AddKey mSC-Click,"Breakpoints clear §" 


Note that no two modifier click key equivalents are exactly the same with respect to 
the modifier key combinations; the first is msOcr, the second is msOcR, and so on. 

Using the Repeat Modifier 

As was mentioned when describing the AddMenu command, the repeat modifier 
treats the time that a key is held down as a modifier. In the modifiers field, a lower 
case Y stands for not holding the key down up to the repeat threshold time, while 
an upper case ‘R’ means holding the key down beyond the key repeat threshold 
time. The second case is said to have matched the repeat key invocation. 
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The AddKey command uses the repeat modifier in a slightly different way. A 
lower-case r, as in msocr, means match on the first click with command, shift, 
option, and control not held down. An upper-case R, as in msocR, means match on 
the second or subsequent click with command, shift, option, and control not held 
down. 

For example, the two commands below create number windows. The first one 
creates a number window with the value of 1 when 36—J is pressed. The second 
one creates a number window with the value of 2 when 3€- j remains held down. 
Try typing in the two commands below and hold down 36-J for a couple of 
seconds. 

AddKey Mr-J,"New Number 1" 

AddKey MR-J,"New Number 2" 

Typically the “1” or “L” modifier is not specified, since commands should usually not 
be dependent upon the position of the caps lock key (up or down). However, this 
modifier can be specified and used to qualify commands based on the state of the 
caps lock key. 


DeleteKey 

DeleteKey unbinds a key equivalent specified by modifiers and keyCode. (See the 
AddKey command for explanations of modifers and keyCode .) The command format 
is: 

DeleteKey [modifiers -] keyCode 

AddLabel 

TMON maintains label tables which you can add to with the AddLabel command. 
An example of using this command is the following: 

AddLabel WierdPlace,50,4 

will place an absolute label WierdPlace at location $00000050 (four bytes long) 
that you can look at with a Dump, Assembly, or Memory window. Placing new 
absolute labels in memory using this command is a rare event even for Macintosh 
system developers. 

For command syntax and further details, refer to Section 8.5.1 of the Technical 
Reference. 

Map 

The Map command permits you to map the range of memory from a starting 
address to an ending address in a monitor, user or custom TMON address space. 
For example, it is possible to map a range of user memory to a specific range of 


TMON Professional Tutorial 


117 


Chapter 7. Scripting for Fun and Profit 

direct addresses. It is even possible to mark a range of addresses as invalid (using 
the • character in the Map command). 

The Map command can be useful to NuBus card developers since it can map in 
areas of a card’s minor and/or major NuBus slot space which TMON might map 
out of the address space by default. 

The physical and direct address spaces naturally can’t be remapped. Refer to the 
Technical Reference (section 8.5.1) for the command syntax and further details. 


Debugging Commands 

The debugging commands Trace, Step, Gosub, Breakpoints, and Traps; exit 
commands (e.g., RTE, Exit, MagicAddress, MagicReturn, PopA7, and 
PopA6 ); along with related windows (e.g., Identifiers, Assembly and 
Memory ) are introduced in Chapter 8 of the Tutorial. 


Utility Commands 

The following block commands may include an optional field for specifying the type 
of address space that is to be used. The options are: 

memory command preferences ::= [ /Physical, | /Direct, | /Monitor, 

I /User, | /Custom, ] [ 32Bit =bool ] 

Move 

It is sometimes handy to copy blocks of bytes of all sizes from one memory location 
to another. The command Move is provided to do this. The format for Move is: 

Move [ preferences ] start-address, .end-address, target-address 

The block of bytes from start-address to end-address will be copied to memory 
starting at target-address. The bytes at start-address and end-address are included in 
the copy. This is a copy operation. The contents of memory ranging from start- 
address to end-address will not be overwritten unless target-address falls inside of 
that range. The byte at end-address will wind up being copied to target-address + 
end-address - start-address. 

For further details, check the more complete description of the Move command in 
the Technical Reference. 

Fill 

A memory fill routine is always included in saavy debugging packages; TMON is no 
exception. The format for Fill is straightforward: 
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Fill [ preferences] start-addr. .end-addr, value 

The command simply fills the bytes from start-address to end-address with the 
indicated value. However, the value doesn’t have to be a hexadecimal byte value; it 
can be any integer, datum or a string of any length. The start-address can also be 
greater than end-address. In this case, the value is still written into memory from 
start-address to end-address. 

Check the complete description of the Fill command in the Technical Reference for 
further details. 

LoadResource 

There are times when you simply can’t wait for a program to load certain resources. 
You may want to set a breakpoint within a resource that hasn’t been loaded yet, 
look at the code or perhaps check the performance for dramatic changes by 
preloading certain resources manually. Here’s the format for LoadResource: 

LoadResource Type ® [ID | Name] 

where Type is the resource type, ID is the resource ID number, and Name is the 
name of the resource. Type can be any expression that returns a standard 
Macintosh four-character resource type. You can specify either the ID number, a 
value from -32768 to 65535 inclusive or a string that contains the name of the 
resource. 

Using the ® or ®f operators in the Type , ID or Name expressions above may cause 
unexpected results. 

For further details and caveats, check out the complete description of the 
LoadResource command in the Technical Reference. 

Discipline 

Discipline can check parameters passed to OS and Toolbox routines, then enter 
TMON in the event it finds a parameter(s) which fails to pass an integrity check. 
This allows you to find the cause of a bug before you crash. This command is one 
way to control Discipline. The other way is to open a Trap windows preferences 
area, accessing the Trap window’s Discipline line. In fact, this command has the 
same effect as typing in a Discipline configuration command on the Discipline line 
of a Traps window. The Discipline command format is: 

[New] Discipline string 

Because Discipline commands are independent of TMON, refer to the Discipline 
release notes on disk for further information regarding strings which can be passed 
to Discipline. 

If the New keyword is used in this command, then any message returned by the 
Discipline command is displayed as a TMON alert 
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Wait 


The unadorned use of Wait causes TMON to wait for a button press of any kind 
before doing anything else. As such, it is a handy command to force TMON to wait 
for you. 

But wait: there’s more. Two optional fields for Wait are tick-count and bool- 
expression: 

Wait [ tick-count ] [, bool-expression ] 

Both optional fields are straightforward: tick-count is the integer number of clock 
ticks that the Wait command will do its thing. The bool—expression is continuously 
evaluated until it returns a true (non—zero) value. The Wait command may have 
either or both fields present and will stop waiting whenever either the tick-count 
expires or the bool-expression returns true. 

The tick-count may be zero or negative, in which case the Wait doesn’t wait. 
Pressing ^-Period will kill a Wait at any time. 

UserScreen 


Typing the UserScreen command displays the user screen. Use a call to Wait right 
after UserScreen. To see this command in action, define a TMON alias like this: 

Alias Testeroo,"Userscreen dn Wait” 

and then invoke it. The results should be no big deal—the TMON menu will vanish 
from the screen until you do something. 

MonitorScreen 

This command displays the TMON control menu and any open TMON windows. 
MonitorScreen can be used in a script for toggling back from a UserScreen 
command. 

Alert 

Draw a TMON alert box across the top of the display, with a specified message 
The format is 

[New] Alert string-expression 

Using the New keyword with the Alert command is not necessary. 

Use of this command is likely to be rare. 
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Error 

Draw a TMON alert box across the top of the display, including the error string. In 
the event that an error string is not defined for the passed error, the format 
displayed is 

Error #$number 

in the alert. The number is specified as the command’s only parameter. The 
command format is 

Error error-number-expression 

Use of this command should be rare. 


Scramble 

The Macintosh memory manager supports non-relocatable and relocatable blocks. 
A common programming error is keeping an address of a relocatable block and 
continuing to use that address even after an operation is performed that could cause 
the contents of that block to relocate in memory. If a stale address is used, incorrect 
results can be read, and areas of RAM can become corrupted. This can result in 
intermittent crashes, corrupting data. 

Because this type of error can be made, yet not show its face until much later in the 
life of the product (perhaps after release), it would be good if there was a method to 
try to force this type of error to occur. One way of doing this is to force all 
relocatable blocks to move whenever it is possible for them to do so. This is called 
scrambling the heap. 

To scramble a heap at a given address, type the Scramble command: 

Scramble address 

where address is the address of a heap known by a heap window. TMON does its 
best to move relocatable heap objects around so that it is possible to catch handles 
that haven’t been properly updated ( dereferenced) before being used to access a 
relocatable block in the heap. This kind of insidious software defect can linger 
undetected well after final testing—without the premeditated software exercise 
provided with Scramble. 

This performs an immediate scramble of the heap. For shaking down handle 
dereferencing bugs, it is best to turn on heap scramble from the traps window and 
ask TMON to perform the current heap operation for all traps. In doing so, anytime 
it is possible for relocatable heap blocks to move (e.g., when allocating memory), 
the block will move. This can force hidden bugs to surface which might otherwise 
be extremely difficult to reproduce. 
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Purge 

Sometimes software expects (wrongly) that purgeable blocks haven’t been 
removed without checking that they’re still around. The Purge command is 
provided to explicitly remove purgeable blocks from the heap to make defects of 
this nature stand out. The command is similar to Scramble: 

Purge address 

where address is the address of a heap known by a heap window. 

This performs an immediate heap purge. For shaking down block purging bugs, it 
is best to turn on purging from the traps window and ask TMON to perform the 
current heap operation for all traps. In doing so, anytime it is possible for purgeable 
heap blocks to be purged (e.g. when allocating memory), they will be. This can 
force hidden bugs to surface which might otherwise be extremely difficult to 
reproduce. 


Editing Commands 

The following paragraphs describe the commands that perform editing operations. 
They are not normally used by typing into a Command window, but are used to 
define scripts that are invoked by pressing key equivalents or with mouse menu 
selections. Among these editing commands are those that require an open monitor 
window to do anything. If no open TMON window is available, then the command 
does nothing. 

The commands are listed here for convenience; a complete description is located in 
the Technical Reference. 


Insert 

This command inserts a character string at the current cursor position. The format 
is: 


Insert string-expression 

A particularly useful example is the command: 

AddKey mSoc-Return,"Insert d"ddnd "" 

This is defined in the TMON data fork and allows the key combination shift- 
return to enter a new line character with an Insert command. With this command, 
multiple script commands can be inserted on a single line. 


Enter 

This command enters the current line as if the Return or Enter keys were pressed. 
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SelectAll 

This command selects the entire current line. 

Clear 

This command clears the current selection. 


Home 

This command moves the cursor to the home position in the window as if the TAB 
key were pressed. 

Cut [/Append] 

This command places the current selection into the TMON clipboard and removes 
the selection from the window. The selection is appended to the clipboard, instead 
of replacing the clipboard contents—if the word /Append is used as a parameter 
(the default is to replace the clipboard contents). 

Copy [/Append] 

This command places the current selection into the TMON clipboard without 
destroying the selection. The selection is appended to the clipboard, instead of 
replacing the clipboard contents—if the word /Append is used as a parameter (the 
default is to replace the clipboard contents). 

Paste 

This command copies the TMON clipboard contents to the current selection. 

Undo 

This command backs out of making the last editing command, or the last indivisible 
set of editing commands. 

Close [/All] 

This command removes the topmost (active) window from the screen—including 
the keyword /All as a parameter will close all currently open TMON windows. 

Clone 

This command creates a new exact copy of the topmost TMON window. 
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Printlmage [/All] 


This command prints the topmost window. No adjustments are made for print 
window width. All windows are printed, if the keyword /All is used as a 
Printlmage parameter. 


Capturelmage [/All] 


This command captures the topmost window. No adjustments are made for print 
window width. All windows are captured, if the preference /All is used as a 
Capturelmage parameter. 


Other Useful Commands 


MouseUnfreeze 


Sometimes when a program goes AWOL during debugging and the mouse freezes, 
the memory-mapped I/O locations for the SCC chip have been walked on 
MouseUnfreeze resets the SCC. Anything that is handled by the SCC will be 
affected, including the Macintosh serial ports. 

Because the mouse is linked to the Macintosh via the SCC only on the Macintosh 
Plus, this command is only enabled for that machine. 


NastyO 


This command loads the hexadecimal value $50FFC003 into the memory location at 
address 0. With NastyO, programs that attempt to use NIL pointers and handles 
may immediately run into a problem that brings up TMON. Otherwise, the program 
may continue for a while before the problem is detected, making it more difficult to 
figure out exactly when the problem started. 


Creating Your Own Commands 

TMON Professional is multi-talented, lovely, and extensible. There are quite a few 
ways to roll your own. With Alias, you can define script commands. With Macro 
you can define brief strings that expand into longer, more elaborate ones. 

Beyond the scope of this Tutorial are other ways to extend TMON: resources, 
DCMDs, user areas, and cooperative applications. For these topics, read Chapter 9 
of the Technical Reference. 
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Alias 

Creating new commands to fit your more specific needs can be done with the Alias 
command. It has the following command format: 

Alias NameThatAliasCommand , "TheAliasScript" 

where NameThatAliasCommand is the name of the alias, and " TheAliasScript' ' is 
the quoted command script to be run when the alias is invoked. 

NameThatAliasCommand must be a proper unique identifier: it can’t contain 
wildcard characters, and it must not already be in use as the name of another 
command. If a new alias is defined with an already used name, the new definition 
replaces the old one. TMON does not provide a command explicitly for removing 
existing aliases. Legal name examples are PopA7, checkVectors, and 
StackCrawl. An illegal example is “Grinch...”. 

The command script of an alias may contain invocations of script commands and 
other aliases. A single command may go up to 100 levels deep. Another legal 
example is: 

Alias Inessential,"New Alert 9"Doodah9” 

Alias definitions should be clean. Although they can have unmatched IF, WHILE, 
TRY, and BREAK commands, they shouldn’t. Aliases can also have any number of 
parameters. 

The delay character, A, can be used in an alias definition. For example, the alias 
StackCrawl (as defined below) uses the delay character. 

The Parameter Replacement Character ‘Q’ 

The special character £2 (Option-z) is used in alias definitions and means replace 
with rest of command line.” Here’s a simple example: 

Alias KitSink,"New Dump £2 9n StackCrawl £2" 

which opens two windows—both keyed by the value of the parameter when 
KitSink is invoked. For example: 

KitSink A6 

The following is a list of some of the alias definitions that are stored in the TMON 
data fork. These are executed during TMON’s setup time. Note that StackCrawl is 
defined as an alias of a memory window. Make certain that you check the contents 
of the actual TMON or TMON Settings data fork for the most current version of 
these aliases. 

// Aliases 

Alias StackCrawl,"New Memory 
/Ascend=l, 'StackFrame' , A£2, §~ : 0" 

Alias MExit,"Wait ,mouseDown () dnExit £2" 

Alias MGosub,"Wait ,mouseDown () dnGosub £2" 

Alias MStep,"Wait ,mouseDown()dnStep £2" 
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Alias MTrace,"Wait ,mouseDown()OnTrace £2" 

Alias PopA7,"MagicReturn £2 A7" 

Alias PopA6,"MagicReturn £2 A6+4" 

Alias CheckVectors,"New Compare /User,0..$FF, 'SavedVectors' " 

Aliases that aren’t stored in the TMON data fork or in the TMON Settings script 
aren t automatically reestablished at TMON boot time. Always work with a copy 
of TMON when modifying anything. 

Special Note: The keyword New may be needed in any alias or script command 
where you need to create a window, like a dump or memory window. So, rather 
than saying: 

Dump A6 

you may need to use: 

New Dump A6 

Macro 


A TMON macro is similar to an alias in that both are used to define a short string 
(the identifier) which translates into a longer one (the definition). The identifier 
Wow can be defined as the name for the macro or alias definition "extremely 
euphoric, rapture and excitement ". Neither macro nor alias identifiers 
may have wildcard characters. 

The most important difference between aliases and TMON macros is that an alias is 
a command, while a TMON macro can be substituted nearly anywhere. 

One difference between alias and macro is simply that an alias can have the special 
embedded £2 (Option-z) characters inserted in the definition (see the description 
for Alias, above), while a macro can’t. Aliases can be nested 100 deep, but there is 
no depth limit for nested macros. 
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This chapter discusses the reasons why this debugger exists in the first place. 
Assembly code and all of its trappings are king here. Any window with anything to 
do with it is covered, including the memory window which has been discussed in 
Chapter 5. 


Assembly Code 

TMON is a powerful assembly-level debugger with powerful symbolic capabilities 
exceeding the base definition of assembly-level debugging. Two kinds of TMON 
windows—the Assembly and the Memory windows— can do disassemblies, but 
there are essential differences. The Identifiers window provides every known 
kind of label or name. The Breakpoints and Traps windows are used to 
establish and control automatic tracing. The Record window provides a visual 
record of the machine’s program counter passing specially-marked traps and 
breakpoints. 


Kinds of Assembly Code 

Some people write assembly code as assembly: each instruction is typed in by hand, 
without the benefit of a high-level language compiler. A skilled practitioner writes 
the tightest and fastest code there is. You can tell when assembly code is generated 
with a compiler, because the compiler does things that nobody would see fit to do: 
it uses registers in a rigid, mechanical and inefficient way, with assembly 
instructions appearing in the generated code that are time-consuming and 
accomplish nothing. So, a big challenge for compiler authors is to make the 
generated code as hot or hotter as the hand-crafted stuff. 

Other kinds of assembly are naturally based on the machine. Not every processor 
in the Macintosh is the same: some are 68000s, 68020s, 68030s or even 68040s. 
These days, a processor can be a 6502 or even an AMD 29000 (the processor used 
on the 8*24GC NuBus graphics accelerator card by Apple). This naturally 
complicates matters, because the 68030 has instructions that aren’t available in the 
68020. The 68020 uses many instructions that the 68000 doesn’t know about; and 
none of the 680x0 processors know much about 6502 code. TMON currently does 
not support the AMD 29000, but all of the instructions for each existing 680x0 
processor are supported. Unofficial support for the 6502 is available as an 
extension—there is 6502 code to be found in the Macintosh ROMs for the 
Macintosh Ilci and Macintosh Ilfx (the Macintosh life uses 6502s as I/O 
processors, but the Macintosh Ilci doesn’t have any 6502s in it at all; go figure). 

Where Code Lives 

Executable code is usually found in one of two locations in memory: 1) within a 
CODE resource, and 2) as part of the Macintosh ROMs. CODE resources are 


TMON Professional Tutorial 


127 


Chapter 8. Debugging Code 


normally found in the heap where they can be moved around, discarded, or locked 
into place for the duration of runtime. 

Looking at Code with the Assembly Window 

An Assembly window can be created (if one doesn’t exist already) by selecting the 
Assembly menu item in the menu or by pressing S€-a ( any existing assembly 

window will be brought to the front). Holding the Shift key down—as always_ 

permits you to create many assembly windows. Selecting the close box or pressing 
K-w closes the current active window, including assembly windows. 

The assembly window displays memory as assembly instructions, whether it is is 
code or not. No attempt is made to interpret the contents in order to see if it makes 
any sense. Memory windows do a commendable job of looking at both the context 
and the content of memory to determine its appropriate display. In a nutshell. 
Assembly windows disassemble anything in memory. A Memory window is more 
selective, and will disassemble when it knows it is looking at a CODE resource or 
some ROM code; it will not try to disassemble data unless told to do so. 

Briefly, About Window Prefixes 

The Assembly window command must have the prefix New before the keyword 
Assembly to create a new window, as in this example: 

New Assembly DoUpdate 

When you are selecting the Assembly menu item, you are actually executing this 
command: 

Open Assembly 

Using the Open prefix, as above, creates a new Assembly window if none already 
exists. If one or more do exist. Open will cause the next window of that kind in the 
list to be selected. New means a new window will always be created. 

Some Differences between Assembly and Memory Windows 

The Assembly window doesn’t know the difference between code and an embedded 
label, it shows embedded labels as assembly instructions. On the other hand, a 
Memory window can make the distinction. Compare the circled area attributed to 
the function DoUpdate in Figure 8.1 with the Dump and Memory windows (Figure 
8.4) that also show DoUpdate. The circled area is actually an embedded label. 
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Q Disassembly from _ 

00460568: ‘GetGlobalMouse’ 
0046056C: ‘DoUpdat e * 

00460578: “ ‘ 

00460572: 

00460576: 

00460578: 

0046057C: 

0046857E: 

00460580: 


100460584: 


0046059ft: 

0046059C: 

0046059E: 

004605A2: 

004605A4: 


00460508: 

004605ftft: 

004605ftC: 

0046058E: 



BCS -*00460568 
LINK.W A6,#*0000 
MOUE.L A3,-<A7> 
MOUEA.L *0008<A6>,A3 


#4, A7 

-*0046059E 
A3,—CA7> 

_BeginUpdate 
SU8Q.L #2,A7 
MOUE.L S0018(A3>,-<Ai 
EmptyRgn 
TST.B <A7>+ 

BNE.S -S0046059A 
MOUE.L A3,-<:A7> 

JSR -*00460610 

ADDQ.L #4,07 
MOUE.L A3,-<A7> 
EndUpdate 

MOUEA.L 'FFFC<A6>,A3 
UNLK A6 

JBI&. 


‘GetGlobalMouse’+*34 


04, D4 
-*004605FF 
#*64,00 
-*00460622 

_-*00460580 

LINK.W A6,#*0000 
MOUE.L A3,-<A7> 
MOUEA.L *0008<A6>,A3 
MOUE.L A3,-<A7> 


;*IsAppWindou 1 
;‘DoUpdate’+*32] 


;‘OoUpdate’+*2E[ 
;‘DrawWindow : 


* DoCont ent Cl»ck’+*10 
; ‘ d 1 

; 1 DrawMindou’+8 
;‘DoUpdate ’+*44 _ 


Figure 8.1 The Assembly Window 

Assembler Window Hidden Options 

The preferences of the Assembly window are a subset of the preferences of the 
Memory window—missing is the line providing the choice of byte, word,^ or long 
dump value organization, or the Standard ASCII checkbox. Everything else 
about the window preferences are exactly the same, as discussed in earlier 
chapters. 


□ Disassembly from *00460568 

Address space: OPhysical OOirect QMonitor ©User OCustom Q32 L_ 

□68000 Q 68010 @68020 @68630 D68040 @68851 @68881 @A000 ®Macros 
Processor family: ®68000 0 6502 

SJStrict EComments @ASCII Comments DUse <PC> DUse S+offsei 
[Capture *00460568.,*0046056C 
|Print *00460568..*0046056C 

BCS -*0046056A 
LINK.W A6,#*0600_ 


■ + 
+ 


@Set Default 


Figure 8.2 Assembly Window Preferences 


Looking at Identifiers 

Chapter 5 of the Tutorial introduces labels and what they can be attached to. Much 
of the need for labels is concentrated in the windows discussed in this chapter. 
Most assembly-level debugging takes place through the use of one of the four 
windows—the Assembly window, the Memory window, the Breakpoints and the 
Traps windows (described next). The Identifiers window will probably help provide 
information without having to go to great lengths to find it 


Creating an Identifiers Window 

Creating an Identifier window requires selecting the Identifiers menu item in the 
TMON menu, or pressing 36—I. 
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o Identifier A000 Trap Window Preferences Box 

Pattern N&rie _ Type _ Address _M^cro Definition \ 


□ Identifiers £S \ / / ' "—/- 1 --- \=~~ 


_Lode3crap: A808 trap *A9F8 / U 


.Long2Fix: A990 trap _ . , /, 

* 

_LongDate2Secs: Assembler macro(*2F3C *3008 *FFF2 *A8B5l 




_LongSecs2Date: Assembler macro *2F3C *3898 *FFF8 *A8B5 


_Lol4ord: A880 trap *A36B 

_LRect: Assembler macro *3F3C *3040 *A3E7 

4 - 

J-Scrotl: Assembler macro *3F3C *9059 *A9E7 



Figure 8.3 Identifiers Window 

Typing a Search String 

A pattern typed in an Identifiers window is used to search for the labels thatTMON 
knows about currently in the system. The ellipsis character, (Option-;) is 
used as the wildcard character. Typing in Return produces a list of all the 
known identifiers that start with the underscore character. 

Example of Embedded Label in CSample.c 

Figure 8.4 contains an example of the embedded label TMON display DoUpdate as 
shown in an Identifiers window, as the embedded string in a Memory window, and 
as shown in a Dump window. DoUpdate is a function contained in the example 
application CSample. To find these locations, simply launch CSample, break into 
TMON when the stoplight appears on the screen, open an Identifiers window 
search for DoUpdate, then take it from there. 


Uiaw #0 Nun #N Uars ««*N Identifiers 91 Regs »R 


Dump SO Assembly SA Memory *M Heap SH File 8L 
Find S F Search S»F Compare 8»M Stack Crawl 8«C 
Brkpts SB Traps ST Record S*R Printing 8P Options #*0 
RTE Exit SE GoSub #& Step SS Trace S*T PopA7 PopA6 ExitToShell S-E 

Copy SC Paste 8U Close 814 Clone 9= Print Top 8»P Capture Top 8»Y 


Undo 82 Cut 8X 


□ Identifiers ' 


‘Double’ 

* OoubleTime’ 

^’uaup jgig'" 


Typ* 

Absolute label *909002F0 
knoeaoeu laoei" *U04Uy" bL \ 
Ausoiule laoei 


V UUUBLI 

‘DPUTPICBYTE’: Absolute label 
‘DPUTPICOP’: Absolute label 
‘DRA6C0NTR0L’: Absolute label 
‘OragFlag’; Absolute label 


□ Memory from :*0040855A 
0040855A: ‘GetGlobalMouse’+*0024: 8E 47 65 74 47 6C 6F 62 61 6C 4D 6F 75 71 *5 f 
4 GetGIoba 1 Mouse’ +50034: ti tc « » 75 73 65 ( 


0040856C;) 


00408572: 

100408576.* 


8040837C: 

0040857E: 


8040859AJ 

0040859C: 


004085A2: 

I004085A4: 


•OoUpdate’ : LINK.W A6,#*0000 

‘DoUpdate’+*8004: MOUE.L A3,-<A7> 
‘DoUpdate’+*0006: MOUEA.L *9908<A6>,A3 
‘OoUpdate’+*009A: MOUE.L A3,-<A7) 
•DoUpdate’+$0000: JSR 
‘OoUpdate’+* 0010 : TST.B 
* OoUpdate’+*0012: AOOQ.L 
‘DoUpdate’+*0014: BEQ.S 
‘DoUpdate’♦$0016: MOUE.L 
‘OoUpdate’+$0018: _BeginUpdate 
‘DoUpdate’♦$081A: SUBQ.L #2,A7 
*DoUpdate’+*001C: MOUE.L $0918<A3),-<A7> 
*DoUpdat•’+*0020: _Enpt yRgn 
‘OoUpdate’+*©022: TST.B <A7)+ 

‘DoUpdate’+*0024: BNE.S 
‘OoUpdate’+*0026: MOUE.L 
‘OoUpdate’+*0028: JSR 
‘DoUpdat«’+*002C: ADDQ.L 
‘OoUpdate’+*002E: MOUE.L 
‘OoUpdate’+*0030: _EndUpdate 
‘DoUpdate’+*0032: MOUEA.L V FFFC<A6>,A3 
‘DoUpdat*’+*0036: UHLK A6 
4 DoHnd»t»>»tt«nft? PTC 


/ '*0040896A 

D0 

#4,A7 

/S *0040859E 

A3,-<A7> 


-'♦0040859A 
A3.-CA7) 
•'“*0040861A 
#4, A7 
A3>—<A7> 


eGet 61oba1Mouse.f 


5 4 IsAppWindow 1 


;‘DoUpdate'+*3a 


4 DoUpdate’+*20 


004085B6: 


□ Dump from 


‘DoUpdate'+*003A: 88 44 6F 55 70 64 61 74 

4 Pow L ' t 1 v Jg e* "" 1 ."ctrryw mw oev * .- 

4 OoActjvat»’+*0004: MOUE.L A3,-<A7) 


65 00 00 00 


aOoUpdate... ) 


00488576: 


‘GetGlobalMouse’+*0030: 75 73 65 00 00 00 4E 56 00 00 

‘OoUpdate’+*000A: 2F 08 4E BA 33 F0 4A 00 58 8F 

•DoUpdate’+*001A: 55 8F 2F 28 00 18 A8 E2 4A IF 

* DoUpdat e’ +*002A: 00.84 SB SF PF AR A A 23 R4 AF 


□ 

2F 08 26 6E 00 08 use... NU.. ✓. . <1 

67 1C 2F 08 A9 22 AN/. *J.Xeg+r,. 
66 08 2F 08 4E BA U^+. .0>J+fdAN/: 

tf fq 4f gp 4 f 7 ? ms mHvn.xW 


, **1 ^ 70 64 61 74 65 03 00 00 4E 56 09 00 aQoUpdatet ‘.NIT. 

OoActivate’+*0094: 2F vv 2 b bt W m ZTW 4k jjfl 03 ’ hA 4A W b8 U» Atn. .‘M.Xeji 


Figure 8.4 Example Identified Embedded Label 
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These options come in two groups: 1) code identifier options and 2) TMON 
identifier options. Code identifiers are labels associated with code in memory. 
TMON identifiers are labels associated with the operation of TMON. You can, for 
example, get an alphabetical listing of all the TMON commands by selecting only 
the Commands checkbox and typing ... and Return. Other things that may be of 
interest are all the current dcmds, aliases, and macros. 


Code [dentjfiers 


□ Identifiers Ua , 

[§] Absolute ®A4-rel*tive®A5-relative ®A6-relati' 
®A000 ®Asn Macros ®Types 
□Comands Q OCMDs DAIiases □Macros 
Capture ——— 

iPrint **_" 


X 


®A7-relative ®Resource-relative ®Embedded' 
□Clear Enables ®$et Default 


a 


TMON Pro Identifiers 


Figure 8.5 Identifiers Window Preferences 

Minor Details 

The underscore alphabetically comes after the other letters (in ASCII order), so all 
the traps and macros with labels starting with an underscore will follow all the other 
labels in an Identifiers window. 

Although TMON scrollbars lack thumbs, you can quickly scroll to the bottom of a 
list by holding the mouse button down over a down page arrow. 


Recording, Traps and Breakpoints 

Three topics are covered in this section: 1) breakpoints, 2) traps, and 3) recording 
either of them. There is a brief discussion on detecting intermittent heap problems 
with heap scramble and purge, as well as checking for a bad heap on breakpoints 
and traps. 

Breakpoints, In General 

Breakpoints are memory addresses that you think are temporarily special. Any 
viable RAM address can be a breakpoint (Watchpoints in ROM are also possible 
and are discussed later under “Using Trace”.) Breakpoints can be programmed to 
do things when the program counter address hits or comes across them during 
normal program execution. Assigning a breakpoint to a memory address does not 
permanently change the contents of that or any nearby address in memory, so an 
application is not modified. 

A breakpoint is where TMON can say, “Hey, the PC is at address $00520440, and 
there’s a breakpoint there that says to break into the TMON monitor. So, here I 
am!” A breakpoint can be assigned to an address just before something significant 
is done. This means that a program can execute freely until the critical moment 
arrives, then stop at the breakpoint—permitting you to watch what happens next 
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easily. In this way, some breakpoints can be thought of as the temporary interface 
between the code that executes freely and the code you intend to single-step 
through. 

How Breakpoints can be Used 

TMON breakpoints can do more than simply cause a break into the monitor. 
Breakpoints can be activated and counted, execute expressions, provide formatted 
output. And, they can be recorded. 

Breakpoints peppered across the landscape of your code can be used to record the 
part of a program most recently ran before the program bombed. They are also 
used to count the number of times sections of code are used. Calling a deallocation 
routine more than once can be remarkably bad if the object has already been 
deallocated. A peek at a breakpoint window will reveal the number of times a 
breakpoint has been hit; a look at a record window will show the most recently 
executed breakpoints (and traps). 

To Trip or Not 

Sometimes a breakpoint shouldn’t trip if certain conditions aren’t met; it is easy to 
set operating conditions for breakpoints to do nothing (e.g., the first four thousand 
times the program counter comes roaring through or only if a block of memory 
changed and the option key is held down). 

Heap Manipulations 

Here’s how to turn some intermittent bugs into reproducible ones. Breakpoints can 
be used to scramble the heap, which means moving some or all of the objects stored 
in the heap, at the best time. One of the most insidiously evil kind of problems you 
can run into is an intermittent one, which occurs at its leisure (perhaps once a 
week, maybe less often). A problem like this may be due to the Macintosh memory 
manager moving the contents of the heap around and catching your dereferenced 
handles off guard. Moving heap contents is done on an as-needed basis to make 
room for new heap objects—it is time consuming. Making a call to the Macintosh 
ROM for a toolbox or OS operation or a call to a routine in a different code segment 
can lead to relocation operations by the memory manager. When a program is 
running comfortably on a machine, the memory manager may not have to shuffle 
things around very often, making problems with heap objects harder to turn up. 

When a program makes use of an object on the heap, the program normally 
references an object using a handle, allowing the memory manager to move things 
around and still maintain a valid handle. If you always use the handle the way it was 
meant to be used—doing a double-dereference every time you access a heap 
object—then you will always point to the relocatable object in heap, and you’ll never 
need to do a heap scramble. If you are in the habit of making and using pointers out 
of handles in order to speed access for time critical situations, be forewarned that 
the memory manager is not responsible for updating anything except legitimate 
handles. Pointers are left behind in the dust when something is moved. 

Scrambling has the effect of narrowing down problems with code that may 
reference data objects in the heap using pointers. Scrambling heap in breakpoints 
reduces the need to single-step through code when looking for intermittent bugs. 
You can set some breakpoints and let the program run at full speed, while TMON 
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attempts to intentionally cause and detect wayward pointers. A heap scramble is 
CPU time consuming, but it is an excellent way to make some intermittent bugs 
into reproducible ones. 

Breakpoints can also purge the heap, which means removing everything that is 
purgeable from the heap. This is great for testing for outdated pointers and is also 
CPU time consuming. 

Checking the heap, another somewhat time consuming job, is the last kind of heap 
action that can be performed on hit breakpoints. A heap check is a way to make 
sure that the current heap is okay. Scrambling or purging a bad heap does nothing 
good and may obscure the real cause of an apparent problem. 

Permitting Interruptions 

Two flags control the time TMON should activate. The intercept flag is the only flag 
on by default: when a breakpoint is hit, then TMON will activate and execution of 
the application code will stop. When the flag is turned off (shown as a lower case i), 
TMON does not activate and does not appear on the screen. 

A breakpoint marked with the signal flag on (shown as an upper case S) means that 
the breakpoint is a safe place to break. If an attempt is made to manually stop 
execution with the “safe” manual break, pressing the Option and interrupt keys, the 
break will occur there. 

Pressing a slightly different key combination, SS-Option, gets you an emergency 
TMON restart. This is oblivious to the setting of signal flags or breakpoints. 


Q Memory from :*00000510 
00000910: ‘CurApName’ 


®check Qpurge ®scramble Use only zone: 


□ Breakpoints 
Heap operations: 

Capture 
Print 

R=record H=heap S=signal 1=intercept 

addr: ^condition,limit,count: Brecon 
«RhsI» *00261016:: 

«rhsl» *00261020: 1 
«rhsl» *0026102E 


"CSanple” 




□ Memory from :APC , _ __ 

00261002:P ‘SetLight’ : LINK.W A6,#*0000 

00261006: ‘SetLight’+*0004: MODEM,L 07/A3,-<A7> 

I0026100A: ‘SetLight’+*0008: M0UE.8 *000F(A6>,D7 

I0026100E: ‘SetLight’+*000C: MOUEA.L *0008<A6>,A3 

00261012: ‘SetLight’+*0810: CMP.B 'FD92<A5>,D7 

00261016:* ‘SetLight’+*0014: 8EQ.S •''*00261026 

00261018: ‘SetLight’+*0016: MOUE.B D7, 'FD92<A5> 

8026101C: ‘SetLight’+*001A: MOUE.L A3,-<A7> 

0026181E: ‘SetLight’+*001C: _SetPort 

100261020:* ‘SetLight’+*001E: PEA *0810<A3> 

00261024: ‘SetLight’+*0022: _lnvalRect 

00261026: ‘SetLight’+*0824: MODEM.L 'FFF8<A6),D7/'A3 

0026102C: ‘SetLight’+*002A: UNLK A6 

0026102E:* ‘SetLight’+*002C: RTS 

08261030: ‘SetLight’+*002E: 88536574 4C696768 74000000 

8826103C: ‘OoCloseHindou’_ : LINK. 14 A6,4*8000 _ 


‘ Set Light ’ +*24l 


aSetLight.. 


Figure 8.6 Breakpoint Window with Two Memory Windows 

Setting and Deleting Breakpoints 

The first and most common way to set a breakpoint is to hold the Control key 
down, move the cursor over an address, and click once with the mouse button. This 
creates a one-shot breakpoint which will evaporate when hit once. Double-clicking 
creates the one-shot breakpoint as well as exits the TMON monitor—effectively a 
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breakpoint set-and-go. If the Option key is also held down, then the break point 
will be persistent instead of a one—shot and will not evaporate when hit. 

The second way of setting a breakpoint is by typing in a breakpoint command in the 
top line of the breakpoint window. 


A third way is to type a breakpoint script command in the command window We’ll 
get into the details shortly. 

To delete a breakpoint, press Shift-Control while clicking on its location. If 
more than one breakpoint is defined at an address, the asterisk stays until all the 
breakpoints are removed. 

A second way of deleting is to clear the breakpoint line in a breakpoint window and 
press Return. A third way of deleting is to type the breakpoint address in the top 
line of a breakpoint window, prefix it with the keyword clear, and press Return. 

Traps, In General 

On the Macintosh, the ROM-based operating system and toolbox routines are 
accessed using a feature that is provided on all Motorola 68000 family CPUs, called 
the Line A emulator opcodes, or A-line instructions, or A000 traps. Macintosh ROM 
calls are so commonplace and numerous that the A000 traps are dedicated to them. 

Rather than using a jump to effective address instruction QMP) or a jump to 
subroutine at effective address instruction (JSR), A000 traps are an inexpensive 
method of accessing code that is always going to be present in the system (The 
exact whereabouts in the system are a mystery to the application program.) 

An A000 trap appears as a 16-bit machine instruction with the value $A in the top 
four bits; anything goes in the bottom twelve bits. Since the Motorola 68000 CPU 
^T! ly v d °u Sn ' t USe madline instructions beginning with the binary pattern 1010 
(SA), the binary pattern is immediately recognizable as a Line A opcode and causes 
an exception through interrupt vector 10. Apple’s trap dispatch code looks at the 
bottom twelve bits of the A-line instruction to decide which of the possible 
functions was intended. On the Macintosh, the dispatch routine decides whether 
the trap is an OS call or a toolbox call, and uses the correct dispatch table to invoke 
the appropriate routine. 

I'M ON supports watching A000 traps with all of the mechanisms that have been 
afforded breakpoints: decrementing a counter, evaluating an expression, recording 
the occurrence, and bringing up the TMON monitor. TMON can record the 
occurrences of all or a selection of the A000 traps. Trap watches can check, purge, 
and scramble the heap. In addition they have intercept and signal properties iust 
like breakpoints. 
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Discipline Command Line 
(When Discipline is Present) 


Configuration Options 


Top Line DebugStr Toggle 

^ I 


Trap Qualification 


zi 


Heap Zone Selection 


□ Traps • 

®Break on .Debugger and .DebugStr traps 
□Only act on traps belou interrupt level: 1 
□Only trace below interrupt level: 1 

Heap operations: ®check □ purge ®scranble □ check on all 

No Discipline present — ■ -— 

Capture — 

Print 


X 


Use only zone: 


|R=record H=scranble D=discipline S=signal I=intercept 
trap..trap: Acondition,lirtit,count: PrecordExpr, 
«rhSi> .WaitNextEvent 
«rhSi» GetNextEvent...EventAva 
«Rhsi» 6*2AA^<PC^PC<*130- 


V 


linit,cour 

IX 




. Trap Action Legend Print/Capture Buffer Lines 

Trap Action Flags ., ' _ . .. 

K Mysterious Trap Action 


Figure 8.7 Trap Setting Window 
A Humble Suggestion: Program Stress-testing 

When you think it is time, do a scramble or purge on all traps. TMON performs 
these operations only on the traps which can actually move memory. 

Discipline 

Traps have an option, called discipline, that is not shared with breakpoints. Another 
debugging nightmare is getting ROM call parameters wrong. If you make it 
through a compile without detecting an error, you may still be susceptible to out- 
of-range parameter values or inappropriately coerced types. Discipline simply 
checks the parameter list to see that the values make sense before they are used, 
causing TMON to break in when something is amiss. Discipline really slows things 
down when turned on globally. Fortunately, discipline can be selectively activated 
for individual or groups of traps by using the D flag for each entry in the Trap 
window. Also, you can add additional conditionals such as only Discipline traps 
called by your application. Because the ROM calls are largely devoid of runtime 
error checking, goofy, extra or missing parameter values can easily bomb 
applications in ways that make it harder to trace where the problem occurred. 

Recording the Happenings 

With the record flag on (a capital R), the Record window provides a historical 
account of breakpoints and trap watches that have been marked in the Breakpoint 
and Trap windows, respectively. The contents of the record window are 
straightforward. For traps, you are given the time (in ticks), the value of the 
program counter, and the name of the trap. Usually, you are provided the trap 
parameter values that will fit on the screen—provided that the Trap Record user 
area file is placed in TMON Folder. You also can easily record any information 
evaluated from a TMON expression (such as the value of a memory location or 
register or the status of the option key). Finally, the trap call was made from the 
address contained by the program counter, but where is that? The rightmost 
column reports the name of the call-originating routine or code segment, plus the 
offset. This information may save you the trouble of creating an assembly window 
by clicking on the PC location. Because code resources are generally relocatable, 
the program counter value alone isn’t always useful information from execution to 
execution. You always have to be told what the address is symbolically. 
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Breakpoints are normally shown as the current time, the breakpoint address, and 
the symbolic PC address is in the rightmost column. But, you can define a record 
expression and an expression format to print useful additional information in the 
middle area of the record window. 


Line Number Shown at Top of Window 
V Trap Name 


□ Record . 

.0135366 $00626FE3 _UaitNextEven».: 
.0195366 *00627764 _SetCursor*: 


Useful Additional Information 

■f 


_GetCursor: 

_PtInRgn: 
_LocalToGlobal: 
_GetMouse: 
_FrontUirtdou: 
_GetMHandle: 
_FrontWindow: 


.0195366 *0062775E 
.0195366 *00627740 
.0135366 *00627740 
1.0195366 *00627730 
.0195366 *0062772C 
.0195366 *00627622 
.0195366 *00627600 
.0195362 S00626FE3 _WaitNext Eveni: 
.0195362 *00627764 SetCursor: 
.0135362 *0062775E _GetCursor: 
.0195362 *00627740 .PtlnRon: 
.0195362 *00627740 LocalToGlobal: 
,.0195362 *09627730 _6*tMouse: 
.0195362 *00627720 _Front Window: 
'-0195362 *00627622 .GetMHandle: 
.0195362 *00627600 FrontWindow: 
.0195362 *00627F4E SetPort: 
.0195362 *00627F43 EndUpdate: 
.0195362 *00627F42 CopyBits: < 
.0195362 *00627F26 _BeginUpdate: 
.0195362 *00627F20 UalidRcn: 
.0195362 *00627FtA DisposRgn: 
,0195362 *00627F14 _SectRgn: 
.0195361 *08627F06 _0fsetRon: 

r- ^ - 

\ Program Counter 

The Time In Ticks 


<nask =*FFFF, UAR EventRecord-*0063^00, s 1 eep=*00000004. nouseRon=*S 


<-'Cursor=*2062E364> 
<id=.128> 

<C.506,.5379,*00626EF 0 > 
<UAR Pt=*0063AC£C> 

<UAR Pt =*0063ACEC > 


<> 


; . 130> 


More Recent 


;* GETMOUSECURSOR’+*44 
;‘GETMOUSECURSOR'+*3E 
:'GETMOUSECURSOR'+*2C 
J *GETMOUSECURSOR'+*20 
;* GETMOUSECURSOR'+*1A 
;‘GETMOUSECURSOR'+*C 
DOMENUS’+*28 
DOMEMUS'+*10 


; DUMENUS +*1£ 

< Mask =*FFFF,UAR Event Record=*0063AE0C,s1eep=*00000094,nous eRon=*00 


< ■'Cursor=*2862E364 > 
<id*.128) 

< C.506,.537>,*90626EF0> 
<UAR Pt=*0063ACEC) 

<UAR Pt=*0063ACEC> 

<> 

<id=.130) 

O 


GETMOUSECURSOR'+*44 
, GETMOUSECURSOR'+*3E 
;‘GETMOUSECURSOR’+*2C 
| pec Rpront GETMOUSECURSOR’+*20 

Less nuceru getmousecursor’+* i a 

;‘GETMOUSECURSOR’+*C 
:*OOMENUS'+*28 
; 4 DOMENUS’+*10 
J * D06RAPHICS’+#8A 
;'DQGRAPHICS’+*84 
0». 241,. 4730, dstR=*C.0, .8,. 24... 

:‘DOGRAPHICS'+*62 
OOGRAPHICS’+*5C 
00GRAPHICS’+*56 


<*00628428) 

<w £ ndou a *00628428) 

■srcB=*006284CE, A dstB-*0062842A,srcR' 

< uindow=*00628428> 

<*00626EFC> 

<*00626EA8) ■ J * UUbKRKHICS' 

< r gnA=*90626EA8,rgnB=*00626EF» dstRon=*00626EF8) 

_ <*90626£fl8,h=-.339,v=-.324> J _; ‘00GRAPHICS’+*42| 


Trap: Address of A Trap Call 
Breakpoint: Address of Breakpoint 


Figure 8.8 Record Window 

To activate a record window, open a record window, make the configuration options 
visible by selecting the button at the top right, and then specify a size greater than 
zero bytes for the record buffer by indicating the new size in the first numeric field 
on the left (on the second line of the window): 


Record Window Configuration Options 


17* 


□ Record _ 

Use *00001000 byte* For buffer EUStop when full 
Capture *00000000..*00000014 
|Print *90000000..*000000l4 

SXtSI™ -U»i»N«xlEv„n»: Cfw.k-JFFFF.WW Ev^iR.cord»»a3436EM,5l^,p.»00000004.nou».R 9 n.*0 , 
■.I S 0? 2KSZ2 -f e l C 2 r30r: <''Cur5or=»00436O52> ;•6ETMOUSECURSoS-,»6S 

•!f 2SJ255 -o t ! n S 9n: (t.6l4,.474>,*M4agC> ;'GETM0USECURS0R’+*53 

,r dA AiA-k .*ccrMn.iccriiocnD»4.e')f4 


Figure 8.9 Record Window Configuration 

To clear the entries in the record buffer, just click the clear button on the right or 
enter /clear on the top line. 


Typing Breakpoint Commands 

There is a complete, elaborate description of the breakpoint script command in the 
Technical Reference. The more salient parts are explained here. 

There are two forms of the breakpoint command: One is for typing at the top line of 
a Breakpoint window. The other is for typing into a Command window or in a 
command script (like the TMON startup script). The long-winded form is for the 
Command window and command scripts; the short-winded form is for the 
Breakpoint window top line. The difference in wind isn’t much: the long form can 
contain an optional window prefix, and must contain the keyword Breakpoint s to 
identify the command. For example: 
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Breakpoints $0003F020 

The commands work like this: you can set and clear breakpoints. Clearing 
breakpoints is easy—type in the keyword clear and follow that with an address of an 
existing breakpoint or use the keyword all to remove all existing breakpoints. 

clear DoMenus 
clear all 

Setting a breakpoint in the simplest form is easy—type 

$0003F020 

to make a breakpoint at the indicated address. This breakpoint is not a oneshot, and 
the only flag turned on is intercept. There are no additions or constraints to the 
breakpoint’s operation. 

Trigger Descriptions 

The following examples show how to embellish a typed—in breakpoint to be more 
selective on how soon a breakpoint should activate. In the first example: 

$0003F020:1 

the number immediately following the colon (“:’) is the first optional field of the 
trigger description. This number must evaluate to true when the breakpoint is to 
activate when hit. Normally, this field is empty, fhe number 1 means that it will 
behave like a reasonably unsophisticated breakpoint and always activate when hit. 
You don’t even have to even mention it unless you want to get fancy there or wish 
to indicate one or both of the other fields in a trigger description. Here is the next 
example: 

$0003F020:1, 0 

It creates a oneshot breakpoint. The new number at the end is the number of times 
the breakpoint must be hit in order to activate. The 1 means that it needs only one 
hit. A 0 means that this breakpoint is a oneshot and will be removed from the list 
when it is hit. The final trigger field is used as follows: 

$0003F020 :1, 5, 4 

This last field is the countdown counter. In this example, the number 4 means that 
there must be four more hits before the breakpoint activates. It also means 
implicitly that there has been one hit on this breakpoint, because 4 is one less than 
5. 

Break Actions 

Break actions deal with configuring those break action flags that are found on each 
breakpoint entry in the window. They also involve the heap action buttons found 
among the breakpoint configuration options in the window preferences section. 
Here is a list of all of the break actions: 

intercept nointercept 
signal nosignal 


TMON Professional Tutorial 


137 


Chapter 8. Debugging Code 


heap noheap 

check nocheck 

purge nopurge 

scramble noscramble 

record norecord 

They fall into three general categories: heap stuff, break handling, and recording. 

Special Note: check, purge, and scramble are redundant aliases. They can be 
used as synonyms for heap in this context. They perform the currently defined 
heap operation. 

Here is a good example of a breakpoint window topline command: 
intercept signal heap record $0003F020 

The keywords above are break actions which should seem familiar. Intercept, 
signal, heap, and record each set their respective break action flags. Here is 
another example: 

heap all 

All existing breakpoints will have their heap (H) flag set to true (capital). This form 
of breakpoint command only affects the break action flags of existing breakpoints 
Typing 

scramble all 

does exactly the same thing because in this context, scramble is an alias for 
heap. 

The set prefix 

Adding the set prefix to a breakpoint command means that you wish to create a new 
breakpoint, even if one already exists at the given address. For example, typing the 
following: 

$0003F020 
set $0003F020 

will create two breakpoints at the same address. 

Record Window Expressions and Format Strings 

When a recorded breakpoint is activated upon being hit, the record window gets a 
new top entry. The normal information provided for each recorded breakpoint hit 
includes the time in ticks, the breakpoint address, and the symbolic form of the 
address of the breakpoint Often, there is some extra space in the line that isn’t 
used for anything. This space can be filled in by specifying more information when 
defining a breakpoint. 

After you type in the trigger information, you can type a second colon (“:”) and then 
type in one or more record expressions—separated by commas. These expressions 
are evaluated upon activating a recorded breakpoint. 
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After you type in the record expressions, you can type a third colon and follow that 
with an optional record format string —used to format for output the evaluated 
record expressions. The format string operates in a limited way (similarly to how 
the C language character I/O library routine printf operates): you provide text, and 
you occasionally insert a “put next value here” indicator in the string. In.this case, 
the only format indicator available is 3v; you have to type it as ddv to get it to work, 
because it must be “quoted” within the string. Here is an example of using a record 
expression: 

Breakpoints record setlight:: (raouse+2) A .w, mouse''.w 

This example records two values in the record window each time the PC hits the 
routine SetLight. If you want to format the recorded values, an optional record 
format string can be added as follows: 

Breakpoints record setlight:: (mouse+2) A .w, mouse .w: Cursor 
is at ddv, ddv" 


Breakpoint Preferences 

A Breakpoints command may also indicate what heap operations should take 
place when the breakpoint is hit. Importantly, the H flag is set for that breakpoint. 
There are four breakpoint preferences provided for this task: 

/Check =bool Check the heap when breakpoint is hit 

/Purg e=bool Purge the heap when breakpoint is hit 

/ Scramble=&oo/ Scramble the heap when breakpoint is hit 


/OnlyZone=mf Select which heap zone to use 

These preferences occur early in the Breakpoint command. For example, the 
following turns on scrambling for all breakpoints and trap watches that have the H 
flag set: 


Breakpoints /Scrambled 

The preferences precede everything else except the keyword Breakpoints. 


Typing Trap Commands 

As with the breakpoint command, there is a complete, elaborate description of the 
trap command in the Technical Reference. This section provides an explanation on 
many of the trap command options, with examples. 

Like the breakpoint command, there are two forms of the trap command. One form 
is for typing at the top line of a trap window; the other is for typing into a command 
window or in a command script 0ike a TMON startup script). The command 
window and command scripts are longer by containing an optional window prefix, 
and the mandatory keyword Traps. For example: 


Traps _WaitNextEvent 

Traps _GetNextEvent.,_EventAvail 

Traps $000..$FFF 
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Trap watches can be set and cleared. To clear trap watches, you type in the keyword 
clear and either 1) follow that with an address of an existing trap or trap range or 2) 
use the keyword all to remove all existing trap watches. Here are some sample 
trap window commands: 

clear all 

clear _WaitNextEvent 

clear $A000..$AFFF 

clear _GetNextEvent.,_EventAvail 

The following are commands (used in the TMON startup script or in the command 
window) that do the same things: 

Traps clear all 

Traps clear _WaitNext£vent 

Traps clear $A000..$AFFF 

Traps clear _GetNextEvent.._EventAvail 

Setting a trap in the simplest form is easy. Just type 

_GetNextEvent 

to intercept GetNextEvent trap calls. This trap watch will exist until removed. 
Unlike breakpoints, there is no pre-specified way to use a key-combination to 
define trap oneshots. 

Trap Watch Flag Options 

There are a few ways to set up trap recording involving the types of selected traps, 
the time recording starts, what values are recorded, and the display of recorded 
values. 

Each Traps window entry—a trap watch —has five flags that can be toggled by 
hand: 1) record, 2) heap, 3) discipline, 4) signal, and 5) intercept. Each of these 
conditions can also be set when a trap command is issued. If the discipline module 
isn t present in the Macintosh system, the discipline flag doesn’t appear as an 
option. The state of these flags can be set in a regular traps command using the trap 
action options (described shortly). 

The record flag R is used to turn on recording for a trap or range of traps. The 
recorded information is sent to a record buffer which can be viewed in a Record 
window. Breakpoints can also be recorded and viewed in this window. 

The H, or heap, flag controls whether the heap involved with a given trap is 
checked, purged, and/or scrambled. The line which is labelled Heap 
operations (normally hidden in the trap and breakpoint window configuration 
options area) provides square buttons for selecting these capabilities globally. The 
field marked “Use Only Zone:” is for restricting heap scrambling to the area heap 
zone. This is often a desirable thing to do since you are typically concerned with 
stress testing your application by scrambling its heap, but you don’t want to stress 
test another application which may not be as robust as yours. 

The Discipline flag, D, controls the performance of a a discipline check, in the event 
that the trap should occur. If the discipline check reveals a problem, then the 
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program stops and the TMON monitor is activated with the appropriate error 
message displayed across the top of the screen. 

The signal (“s”) flag controls whether the TMON monitor is re-entered when a 
watched trap occurs and the Option—interrupt signal key combination has been 
pressed recently. A trap that is marked in this manner means that it is safe to re¬ 
enter the TMON monitor. There are times when unconditionally interrupting a 
Macintosh application to activate the TMON monitor may cause a problem (e.g., 
corrupting a disk block or track during a write operation). 

Finally, the I or intercept flag indicates that the TMON monitor should be re¬ 
entered unconditionally whenever the trap action is made. 

When creating trap watches, the only flag that is turned on by default is I, the 
TMON monitor intercept. 


Trap Actions 

Each trap command can be given one or more of the following options: 


discipline 

intercept 

signal 

heap 

check 

purge 

scramble 

record 


nodiscipline 

nointercept 

nosignal 

noheap 

nocheck 

nopurge 

noscramble 

norecord 


Special Note: check, purge, and scramble can be used as synonyms for heap in this 
context. They perform the currently-defined heap operation. 

The only difference that exists between the list of breakpoint actions and trap 
actions is the addition of trap actions to turn discipline on and off. For example: 

Traps intercept discipline signal check record __WaitNextEvent 

A single trap command normally contains a trap range, which can be a single trap 
call (like $030 or $A030) or it can be a range of values (like $A030..$A040). The full 
range of legal trap numbers is $000 to $FFF, which can be expressed with the 
ellipsis character, 

After the trap range has been entered, several optional fields can be provided. 


Trigger Expression 
Count 

Current Count 
Record Value Expression 
Record Format String 

The trigger expression is used to Qualify when a trap action is turned on, the 
expression must be true. An example is A3==0. 
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The count is the number of times a trap action must be hit before the trap action is 
turned on. For example, if the command involves a trap range, then the single trap 
count is used for all the traps in the indicated range. This number doesn’t change 
unless you change it. To illustrate: a 3 means the trap action will be turned on at the 
third occurrence of any trap in the indicated range. A value of 0 makes the trap 
action a one-shot which is removed the first time the trap action is hit. A value of 1 
means that the action is to be activated every time. 

The current count is the number of trap action hits that are left before the trap 
action is turned on. 

A record value expression is evaluated and recorded when the record trap action is 
turned on and a record buffer has been allocated in the record window. 

An optional record format string can be used to format and display the results of a 
record value expression. A value can be displayed in the record format string by 
including 99v—a value escape character—in the string. The first 9 character is the 
quote character for the second 9, because it is within a string. It is strongly 
recommended that you limit the appearance of 9v within the record format string to 
the number of values that will actually be displayed. The example below records the 
csCode of the Control call made to the driver whose refnum is -50. 

Traps record _Control: (AO+18)*.SW==-.50 :(A0+1A) A .W:"csCode 

= 99v" 

The expression (A0+18) A .SW==-.50 means “is the signed word at an offset of $18 
(refNum) in the CntrlParamBlockRec pointed to by AO equal to -50?”. The .SW 
means signed word. The sign extension is necessary for this expression, since both 
signs of the evaluate to a 32-bit integer. The word at offset $1A into the 
parameter block is the csCode selector (driver specific function selector); it is 
recorded in the Record Buffer. This can be very useful for tracking the calls made 
to a particular driver. 

Traps Preferences for Turning Traps Off and On 

In addition, a Traps command may indicate the kind of traps operations that take 
place when a trap watch is hit. There are several Traps preferences provided for 
this task. Here are three: 

/TrapIntLimited=i»f, Do not act on traps when the current 

interrupt level is equal to or greater than the 
specified threshold. 

/BreakDebugger=f>oo/, If true, Break on Debugger and DebugStr 

traps (see the important safety tip below) 

/Scramble=2><w/, Enable scrambling during heap operations. 

All of the preferences are listed in Table 7.10 of the Technical Reference. 

Except for the keyword Traps, preferences precede everything else in a Traps 
command. 
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Important Safety Tip—Turning Off Debugger and DebugStr 
Traps 

There are special A000 traps that don’t execute an OS or toolbox function. Instead, 
they are used to intentionally kick into the TMON monitor at appropriate times in 
the application. These “debugging” traps act as a bridge between the source code 
and the executable contents of CODE resources—because debugging traps appear 
in the source code as relatively normal function calls and can be placed and 
compiled where they will make sense within the source code. It is much easier to 
find where you want to be by reading and modifying source files. -Debugger 
merely causes the monitor to activate. When it does, you are given the address in 
the program counter—so you know where the executable code resides in RAM. 
_DebugStr causes a string message to appear with the error message, so that you 
can easily differentiate between different debugging traps. 

Because these debugging traps are normally edited into source files, compiled (or 
assembled) and linked with the rest of the code, they are more difficult to change 
during debugging sessions. You can easily overwrite the debugging trap call with 
$4E71 (a NOP) by using a TMON window. This will prevent you from hitting a 
debugging trap; but it is only a temporary solution, requiring that you change the 
debugging traps one at a time. 

Since they normally require another compile and link to be permanently removed, 
TMON provides a global off switch especially for these traps. (Such a control leads 
one forgetting that these things were turned off at some time...) 

Stepping, Tracing, Escaping, Jumping, and Leaving 
Code 

Measuring how really good a debugging system is starts where developers spend 
time in hand-to-hand combat with buggy code. Once the DebugStr and Debugger 
traps, breakpoints, and trap watches have been set, the heap scrambles and purges 
are wired to “go off at appropriately provocative moments, and you start to 
exercise the program in such a way that does nothing if not taunt something really 
bad to happen, you’re ready to start interactive debugging. Grab the sword and 
drop your visor—we’re off. 

TMON provides commands for a variety of slow waltzes through code—entirely 
under your direction. Some commands are useful for escaping bad situations within 
subroutines (in order to continue debugging further down the line). Other 
commands permit you to execute one instruction, an instruction sequence, an 
entire subroutine or an entire ROM call, before control returns to you again (a great 
time saver). 

Remember that any of the commands covered in this section—including specific 
instances—can be added to the TMON monitor menu window by using the 
AddMenu command. Thereafter, they will be available to you as a selectable menu 
item. They can also be made available as a command key equivalent with the 
AddKey command. 
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Using Step 

Step is about as simple as they come in TMON, although this command has a 
couple of twists of its own. Invoking a Step normally causes the instruction pointed 
to by the program counter to execute. Control is immediately returned to the 
TMON monitor, and the program counter points to the next instruction. The 
predefined keyboard equivalent is Sg-s. 

Twist number one: A000 traps are executed to completion, which means that they 
act as though they were one instruction long. This is okay as long as you don’t want 
to watch A000 traps execute an instruction at a time. If you do, then don’t use Step; 
try Trace instead. 

Twist number two: the Step command (like Breakpoints and Traps) can have 
a trigger field that is used to determine the length a step command should 
continue executing instructions. The format for the trigger is the same as that of 
breakpoints and trap watches: 

boolean expression, optional count, optional current count 

In this case, having both the optional count and optional current count arguments is 
redundant, because returning to TMON terminates the step command. For future 
compatibility, TMON accepts both to make the trigger syntax identical to 
breakpoints and traps. 

Twist number three: a special form of Step command, MStep, switches to the 
application’s screen and waits until you press the mouse button before leaving the 
TMON monitor. MStep through code when you don’t want to release a menu or 
control. 

Triggers Are Handy! 

It is possible to use step triggers to step through code as a function of what the 
code is doing, rather than by predicting the location of the program counter four 
instructions from now. For example, you can set the Step command to stop when 
one of the registers contains a certain value. A Step command with the trigger 
expression Ad 0==0 will continue until register DO contains zero. Step ,5 will step 
five instructions, step 0 continues until you manually enter TMON, reset the 
machine, the power goes off or an error occurs. This is because the trigger 
expression causes a step until true, and zero will always evaluate to false. Trigger 
expressions can be more complicated than these examples. 

Step Options for SysError, Breakpoints and Traps, and Leaping 

Step options are used to indicate what should be done when conditions are ripe. 
The three kinds of circumstances optionally covered by step options are system 
errors, actions, and leaps. Step options are also called preferences and require a 
forward slash (“/”) prefix for each option present. 

These options are normally needed for esoteric debugging situations. 

When a system error occurs, the option /intoSysErr instructs the TMON 
monitor to allow your application to proceed through the SysError trap. The 
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monitor normally replaces the SysError trap execution, since all it gets from you is 
the Dire Straits alert or an enforced Quit from the current application. 

There are three options available for modifying what happens with breakpoints and 
trap watches: 

/SkipActions turns off breakpoints and trap watches for the 

next instruction 

/SkipBreak will not act on intercept (I) and signal (S) 

flags on the next instruction 

/DoAct ions makes sure breakpoints and trap watches are 

active on the next instruction 

There is one option, /Leap (excluding 68000-based Macintoshes where this 
feature isn’t available), which is used to “step over” instructions until a change of 
flow (e.g., subroutine call, a system trap, an exception, or a taken branch) is 
encountered. To illustrate: if the program counter is at the top of ten instructions 
(the last of which is a branch to Boardwalk) issuing a Step /Leap command 
causes all ten instructions to run, the program counter will contain the address of 
Boardwalk when the monitor returns. /Leap does an effective job of speeding up 
Step and Trace. 

Step Option Defaults 

It should be carefully noted that there are buttons in the Registers and Options 
windows that are used to control the default breakpoint and trap watch options. If 
the DoActions preference is off, /SkipActions becomes the default. 
/SkipBreak is the default if DoActions and SkipBreak are on. /DoActions is 
default if preference DoActions only is on. If these preference buttons get switched 
for some reason, then TMON may look like it is starting to do things of its own 
accord. 

(This is patently absurd: Waldemar would never put a virtual intelligence in TMON 
without telling anyone. Nope. Honest.) 

Hmmm. 

In the Technical Reference manual, Waldemar discusses Step option defaults in 
some detail. 

Using Trace 

Step is Trace, except for one minor detail: Step treats an A000 trap like a single 
instruction, while Trace permits you to trace into and through an A000 trap as if it 
was another routine. The predefined keyboard equivalent is 36—T. 

The MTrace command is used to trace through code without releasing a menu or 
control. Like MStep, MTrace switches to the application’s screen and waits until 
you press the mouse button before leaving the TMON monitor. 

Trace can be very useful for watching for a particular condition. Below are some 
examples: 
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Trace change(0,4) 

Trace /leap,change(0,4) 

Trace A0==0 && D0=='STR ' 

Trace /leap,OptionDown() 

The first example traces until the long word at location zero is modified. The 
second example does the same thing but only checks at each change of flow 
instead of at every instruction. The third example traces until AO equals 0, and DO 
equals 'STR'. The fourth example traces until the option key is held down. 

Trace Trigger Expressions: Use with Caution 

Trace trigger expressions are used in the same way as Step trigger expressions, 
but they have a behavioral difference that may catch you off guard. Using a step 
trigger expression is considered to be safer than the Trace alternative, because of 
the dangers involved in tracing through (and stopping at odd places within) the 
Macintosh ROM routines. While step will deposit you in a relatively safe and 
familiar area of your application, Trace may leave you smack in the middle of the 
most alien terrain you have seen. Since you stopped in the middle of a ROM 
routine,, it is possible that the monitor has interfered with the proper operation of a 
time-critical system routine—a potentially dangerous situation. 

To illustrate: because floppy drives are mostly software driven, they are susceptible 
to timing problems caused by attempting to trace through the code—directories or 
tracks could become completely erased. Fortunately, this doesn’t happen with 
normal use, and will only occur if you deliberately attempt to cause trouble. 

Note that under some circumstances when tracing, spurious trace exceptions can 
occur due to software which saves the status register (and thus the trace flags) and 
later restores it. When this happens, just ignore it and exitTMON. This is covered 
in detail in Section 8.3.2 of the Technical Reference manual. 

Using Gosub 

Very similar to Step and Trace, Gosub will execute one instruction. Like Step, 
Gosub treats A000 traps as a single instruction. Gosub differs from step by 
treating the JSR and BSR assembly-level subroutines as though they were one 
instruction: you will see the call to the subroutine, and then you will see the 
instruction after the subroutine call, but you won’t see instructions within the 
subroutine. Hence the name. The predefined keyboard equivalent is 3€—G. 

The syntax of the Gosub command is the same as Step and Trace: 

Gosub step-options,trigger 

where options can be any number of the exit-options that are valid for the Step 
command. For example: 

Gosub /DoActions, D0.W==0 

The above example means that breakpoints and trap watches should behave 
normally, continue stepping until the word in register DO is 0, and then stop 
immediately. Another example: 
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Gosub 

Using the existing defaults for the exit options, execute one instruction, A000 trap 
or subroutine; then return control to the TMON monitor. 

Limits on Using Gosub Commands 

Do not use Gosub on subroutines that rely on looking at the return address on the 
stack, because Gosub removes the true return address from the top of stack and 
replaces it with an address that points to the TMON monitor. This is done to 
provide the monitor with control over what happens upon return from the 
subroutine. 

Don’t use the Gosub with Object Pascal (MacApp) method calls. 

Exit and Exiting 

Exit returns control from the TMON monitor back to the application, allowing the 
application to execute freely. The same exit options used with step, Trace, and 
Gosub can also be used with Exit except for /Leap. Two additional options are 
provided that can be used only with Exit: /UseStackFrame and 
/IgnoreStackFrame. The former indicates that the processor stack frame 
should be used after the TMON monitor activates and takes control to properly 
resume the application. The latter indicates that the processor stack frame is not 
needed and to instead start with the current address in the program counter. The 
following are examples of Exit commands: 

Exit /UseStackFrame, /SkipActions 
MExit /SkipActions 

Return To Elvis 

The rte command is actually a return from exception , and simply involves setting 
/UseStackFrame as an active exit option, and then performing an Exit. Looking 
in the TMON data fork you will find the following command line: 

Alias RTE,"Exit /UseStackFrame" 

If you gander at a registers window, note that it contains the processor and 
coprocessor exception frames that were saved when the TMON monitor came up. 
Exception frames contain information about the state of the processor and 
coprocessor when the exception occurred. 

On 68020, 68030, and 68040-based Macintoshes, it is possible to interrupt the 
processor in the middle of an instruction. Continuing with the application by 
jumping to the saved program counter value may not correctly restore the 
processor state. Instead, an RTE command should be used so that the data stored 
in the exception frames is used. This will happen when either an RTE or Exit 
command is invoked in some situations. See Section 8.3.1 of the Technical Reference 
for details. 
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Leaving Subroutines with Pops and Magic 

While stepping through code, sometimes it is convenient to take leave of a 
subroutine before it has finished executing. There are four commands that make 
escaping a relatively simple matter. 

MagicAddress 

MagicAddress does not itself engineer an immediate subroutine exit; instead, it 
prepares things so that the TMON monitor can activate when a subroutine exit 
does take place. 

If the return address-is somewhere within memory (perhaps on the top of the 
stack), then using the command: 

MagicAddress address 

—where address is the address of the return address, will replace the correct return 
address (usually residing on the stack) with a bogus return address that belongs to 
the TMON monitor. When the subroutine returns, the correct return address is 
inserted into the program counter and a message is displayed: 

an A000 trap or subroutine has returned. 

TMON uses MagicAddress to set up the way it regains control when a Step and 
Gosub is used to execute a trap or subroutine. As mentioned before. Trace 
permits you to step through A000 traps, but Step and Gosub execute them as one 
instruction. 

MagicRetum 

MagicAddress and Exit are combined in this simple TMON command. 
MagicRetum accepts exit options first, as though MagicReturn were an Exit 
command, and then the pointer to the return address in memory, as though it were 
a MagicAddress command. For example: 

MagicReturn /SkipActions,$0003F020 
MagicReturn A2 

PopA7 

The PopA7 command is used to return from a subroutine when register A7 points 
to the return address; this will happen when the LINK instruction isn’t executed 
yet. LINK pushes a number of items onto the top of the stack, including the return 
address. The PopA7 command accepts any valid exit option: 

PopA7 /SkipActions 


PopA6 

What if a LINK instruction had been executed, but not the UNLK instruction, and 
you wanted to escape from a subroutine call? PopA6 assumes that the return 
address has been stored at the location A6+4, and will perform the proper 
unsnarling for you. Like PopA7, PopA6 accepts any valid exit option: 
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PopA6 /SkipBreak 

Exiting Command Key Combinations 

All of the command key presses built into the features of TMON are provided here 


in a small table: 


Exit 

Set one-shot breakpoint and exit 
Exit /IntoSysErr 

MExit 

MExit /IntoSysErr 

se-E 

Control-double-click 

3€-Shift-E 

3€-Option-E 

Sf-Shift-Option-E 

ExitToShell 

St-Control-E 

Gosub 

Gosub /Leap 

Gosub /IntoSysErr 

Gosub /IntoSysErr,/Leap 

3€-G 

K-Control-G 

St-Shift-G 

tfg-Shift-Control-G 

MGosub 

MGosub /Leap 

MGosub /IntoSysErr 

MGosub /IntoSysErr,/Leap 

K-Option-G 

If-Option-Control-G 

S€-Option-Shift-G 

K-Option-Shift-Control-G 

Step 

Step /Leap 

Step /IntoSysErr 

Step /IntoSysErr,/Leap 

§€-S 

s€-Control-S 

3€—Shift—S 

K-Shift-Control-S 

MStep 

MStep /Leap 

MStep /IntoSysErr 

MStep /IntoSysErr,/Leap 

S-Option-S 

S-Option-Control-S 

S-Option-Shift-S 

K-Option-Shift-Control-S 

Trace 

Trace /Leap 

S-Option-T 

3€-Option-Control-T 

UserScreendnW ait 

3€-BackQuote 

Reboot 

S-Control-B 
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Reboot /Unmount 
Reboot /Immediate 
Shutdown 

MouseUnfreeze 

Set 0 to clicked value 
Set New 0 to clicked value 
Set ? to clicked value 
Set New ? to clicked value 
Step Program Counter 
Create oneshot breakpoint 
Create regular breakpoint 
Clear breakpoint 


3€-Shift-Control-B 

3S-Option-Control-B 

96-Option-Shift-Control-B 

3$-Option-Shift-Control-Z 

Option-click 

Option-double-click 

Option-Shift-click 

Option-Shift-double-click 

36 -Option-C ontrol-click 

Control-click 

Option-Control-click 

Shift-Control-click 


It is interesting to note, that the modifier keys work with TMON menu item 
selections, so that selecting the step menu item while pressing the Option key 
results in an MStep command. 
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Displaying memory usefully as byte—wide hexadecimal values is simple. Characters 
are single byte values. Pointers and handles make elocjuent sense in byte—oriented 
hexadecimal even if they spread out over four separate consecutive bytes. TMON 
shows memory as bytes, words, and longs as well. This is more natural for 
inspecting pointers, handles, offsets, and counters; if you know where they sit in 
RAM. 

There are times when being presented a blob of memory in hexadecimal doesn t 
cut it. TMON provides ways of accepting additional context, so that information can 
be interpreted easily. TMON also comes with a large number of predefined labels 
with corresponding type information. 


Inspecting Typed Data 

It is harder to inspect typed data (e.g., a record containing several fields), when the 
fields are shown as a homogeneous grid of byte-length hex values. Face it: records 
and typed fields are used everywhere—even in the Macintosh ROMs. Showing 
records as records and each field in its most appropriate form is a good idea a 
hallmark of modem source-level debuggers. It’s also something TMON can do. 

Memory windows can automatically display values in RAM as typed information 
not as an endless stream of hex bytes. The format must be known by TMON ahead 
of time. TMON must also realize that it is displaying something with a known 
format. TMON knows the location and type of resource blocks in heap and where 
heap blocks are; so, it can automatically handle displaying resources with defined 
record formats. In addition, TMON clearly shows where heap block headers and 
ROM resource map block headers are, but not necessarily what is inside those 
blocks. 

Records that are created by an application during runtime are handled manually: for 
TMON to know you’d like the information displayed in a typed fashion, you must 
enter the type name at the topline of a memory window or in a Memory script 
command. A prime example of this is the stack Crawl menu item, which creates 
a memory window using the StackFrame record type. 

Most predefined labels are associated with types. For example, absolute labels are 
likely to have both a range and a type. CFhe range is the size of the block of memory 
associated with the label.) When you define your own absolute labels using the 
Addlabel command, you can optionally indicate the range and type for the label. 
Also, the Lbl# resources in TMON contain a great number of useful absolute 
labels. When you look at memory near address $00000000, all of those absolute 
label entries are defined in an Lbl# resource. See Technical Reference Section 9.1.1. 
for a detailed description of the Lbl# resource. 


TMON Professional Tutorial 


151 


Chapter 9. Types 

Registering New Type Definitions 

Two kinds ofTMON resources are employed to define types. The Typ# resource 
defines types for use within TMON. (It is introduced generally here, but you can 
find a more detailed description in Section 9.1.1. of the Technical Reference .) The 
RTyp resource is used to describe which defined types correspond with specific 
resource types. For example, a Typ# can contain a description of a DialogTemplate 
record (as well as many more records), and an RTyp resource can associate 'DLOG' 
resources with DialogTemplate records. Thus, anywhere in memory where there is 
a 'DLOG' resource, it will automatically be displayed in a templated format if viewed 
by a memory window. This is far better than a sequence of hex bytes. 

Typ# Resources Contain Type Definitions 

A single Typ# resource can contain a number of record definitions, each of which 
can contain a number of fields. A record definition must have a unique, nonzero type 
number so that it is available for TMON’s use as a type accessible by other defined 
types. 

A record must also have a non-NIL, unique name string in order for you to use it by 
typing its name in a Memory command. If the name is a NIL string, other defined 
types can still use the definition; since they go by the type number. 

Why are there both a type number and a type name? Type names are really for 
human use, while type numbers are for automatic use by TMON. Developers really 
need to use the name strings. 

RTyp Resources Map Resources To Type Definitions 

TMON handles resources well; it knows where resources are in heaps, and what 
their types and IDs are. Resource types with a description in an RTyp resource can 
be displayed more intelligently than in a dump window format. Each record 
indicates a resource type (ResType), whether the resource contains code segment 
and whether it contains embedded labels (both in Flags), and what the 
appropriate TMON type number is (Type id). It also contains a number of 
reserved bits and fields. For details, again see Section 9.1.1. of the Technical 
Reference. 

Creating Typ# and RTyp Resources and Records 

First recommendation: Create new resources and insert them in the TMON 
Settings file. Do not modify resources in the file TMON. It is much cheaper to keep 
multiple copies of the TMON Settings file around than to have multiple copies of 
the TMON executable, which is well over 700K bytes in size. Creating new RTyp 
and Typ# resources is a breeze, to a certain size. 

Please note that some of the resource editing tools available at the time of this 
writing cannot handle large resources. You may have to resort to development tools 
such as Rez and Derez, using the TMON file TmonTypes.r to define the 
customizable resources. 
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When using your favorite resource editing facility, note that RTyp and Typ# are 
both tmpl defined resources. This means that one uses the generic tmpl resource 

editor by default 


Second recommendation: inspect the Typ# resource 256 in TMON, using a 
resource editor. In it you will find two type definitions: Code Segment and 
StackFrame. CodeSegment contains two fields: JTStartOf f set and 
jTEntryCount. StackFrame has three fields: the first without a name, the 
second called A6, and the third called proc . 


Creating a Typ# entry is straightforward. For example, using ResEdit, go^to the 
end of the resource and select the very last thing, a row of five asterisks ( )- 

Then select the menu item New or press 3S-N. Fill in the record as you see fit. 
Select the row of five dashes just below the new record, then select New or 
press Sg-N to create a new field entry within the new record definition and fill in as 
needed. 


RTy#— How TMON Knows About New Definitions 

Getting TMON to recognize that you have created additional RTyp and Typ# 
resources is easily done by following some simple directions. Yet another new kind 
of resource, RTy#, is a TMON resource directory which dictates which resources 
are to be loaded when TMON is installed. 


RTy# Nitty Gritty 

Both RTyp and Typ# resource types have entries in the standard RTy # resources. 
RTy# 256 loads everything and corresponds to the Optional Data= most data button 
in the TMON Loader (see the section on Optional Data in Chapter 2—under 
TMON Configuration in this Tutorial). Rty# 257 corresponds to loading a minimal 
set of data: simple inspection of the LowiD and HighlD field values for the RTyp 
and Typ# entries in both of these RTy# resources may provide some insight here. 


Complication Evasion 

To avoid hassling with changing any RTy# resources, create a new RTyp or Typ# 
resource with an ID number of 1024 in the TMON Settings file. Be careful not to 
make these resources too big for the resource editing tools to manipulate. 

When in Doubt, Load Everything 

Resources with any ID number larger than 256 will be loaded when TMON is 
configured to bring everything in. Please use numbers above 1023 for your own 
resources. Just create the new resources in the TMON Settings file, fill them in, 
and save. They should be brought in the next time TMON is installed. This 
configuration may be too large to use under normal conditions. 


When You Must Create a New RTy# Resource 

Eventually, you may want to modify one or more of the standard RTy# resources so 
that (for example) your new type definitions show up for any of the optional I MON 
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configurations. When this happens, we suggest that you create new RTy# resources 
and store them in a TMON Settings document. 


TMON Professional Standard Types 

TMON directly supports most of the bread-and-butter datatypes used in high-level 
language language development—including Pascal and C strings; 8,16 and 32-bit 
signed and unsigned decimal integers; 64-bit decimal integers; single, double, and 
anything^ fl ° atS ’ P ° mterS and handles to strings, pointers to code and handles to 

TMON also uses types to differentiate the ways in which values should be 
displayed There are, therefore, hexadecimal unsigned 8, 16, and 32-bit integers- 
unsigned 8 16, and 32-bit binary integers; and unsigned 8, 16, and 32-bit octal 
integers All the primitive types are listed in Table 5.7 of the Technical Reference 

£ TMn£ aS ? ^ Pe t nur ? be , r ’ a *Pe name > and a length (the latter being an issue 
when TMON is trying to display the data). 

Some data is a specified length, like a 32-bit integer. Some are variable, like a 
ULL terminated string. Others are endlessly long, and may not be visible in their 
entirety There are two kinds of length: intrinsic and context. Intrinsic lengths are 
those which are specified as the length associated with the type. Context length is 
e length of the space allocated to the object of the given type; this space naturally 
may have nothing to do with the amount of space needed by data of that type. 

Where there are conflicts in length information, TMON uses a predefined heuristic 
to determine the display of that information. For example, if a block of ten hex bytes 
is allocated to contain just one byte-wide item, the first is shown as a hex byte- the 
other nine bytes are also shown that way. If the intrinsic length is longer than fee 
context length, then TMON may show it truncated or whole—depending upon the 
circumstance. F 


TMON Professional Resources 


Already mentioned are the RTy#, Typ#, RTyp, and Lbl# resources-used to 
contain a directory of loadable resources, descriptions of types, descriptions of 
types contained by resources, and all the absolute labels known to TMON 
respectively. There are a few more resources unique to TMON feat are beyond fee 
scope of this Tutorial. These are described in Chapter 9 of fee Technical Reference. 


resources can be added to TMON through user areas or dcmds- 
to add commands and features to this debugging system. 


-two ways 
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Now it’s time to do some honest work. The previous chapters of this tutorial, except 
maybe the Quickstart, introduce each of the TMON features. Here we provide 
some short demonstrations of how TMON can be used. Some useful debugging 
tips are mentioned here, too. 


When Errors Take Their Toll 

Bad error conditions normally cause an appearance of the Dire Straits alert box. 
Rather than the much simpler SysError code show n in a DS alert box, TMON asks 
the System to pass any such errors to it, when installed. Make no mistake about it: 
TMON is automatically alerted to a problem which may have already run its course 
and made a mess of things. 

If a rocket crashes, the rocket engineer is not focused on the crash (unless it s 
somewhat nearby), but on the fact that the rocket went off course. The crash is a 
consequence of a bug (and a really good one for trying to piece together what really 
happened). When the computer decides that an application has gone off course, the 
Macintosh Dire Straits Alert is Apple’s way of trying to make the rocket stop and 
stay in mid-air for users. Developers naturally require more information, and thus 
enters TMON. 


Called Onto the Scene 

Unfortunately, software problems often are not solved by running an application 
until a problem erupts, watching the TMON monitor appear, looking at the 
situation, and quickly fixing the obvious problem. These glitches require sleuthing. 
Sleuthing with TMON needs a little know-how which this chapter introduces. 

Starting on the Trail 

Sherlock Holmes wasn’t especially fond of saying it; nevertheless, he seemed to. say 
it or imply it frequently in conversation with Dr. Watson, bystanders, and various 
Inspectors of the Yard: ‘You see, but you do not comprehend. What the detective 
is saying is that the answer may become obvious if you try to understand what you 
are looking at 

The unarguable truth shared by bugs of all sizes is that the expected didn’t happen, 
and that the unexpected did. These are two things needing to be clearly 
documented right off the bat, and can be difficult to assess because it often calls for 
some homework. For example, you may have to backtrack to find out when a 
problem really erupted. Since you may be confronted with more of the aftermath of 
a problem that started “some time ago,” the proper way to go about that may not be 
obvious. 
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TMON helps you look for the cause of a problem; but unfortunately, it doesn’t track 
down problems for you. TMON makes it all accessible. 

Clues! 

To begin note what apparently happened, as well as what apparently did not 
happen. Understanding what “apparent” means here is important: the program 
blew up or the file contents didn’t get written or the display going blank are 
symptoms of a problem. To find out what’s really happening is going to require 
studying some of the pieces. The elements of the following list are interesting 
proMem f ° r study—using if you are looking at the symptoms of a software 


Display contents Files 
Registers RAM 

Globals 


StackCrawl 

Trap parameters and other recorded values 
Heap 


It is a good idea to think through the reasons each of the components is in its 
current state-starting with the display contents, then investigating the contents of 
the stack, registers, and heap. Fortunately, there is a rational order to follow. 

Ike most common thing to do first is to look at the error message— more often 
than not it is glaring at you on the screen. Be forewarned that this error message is 
potentially misleading information. The error is what caused the application to stop 
out tne message never mentions what caused the error. 

The next thing to do is look at what memory address the processor’s program 
counter (PC) contains. In TMON, this is done using a register window or an 
assembly or memory window that has been anchored to Ape. Related information 
may be available using a StackCrawl window. If you were recording parameters to 
traps and other information, you can look in a Record window. 


An Easy Example—Corrupting the Program Counter 


If the error message is a bus error or an odd address error, then a bad address was 
introduced very recently to the program counter register during the execution of 
the most recent instruction (on a 68020 or ’030 this is the only way to get an address 
error), this may have been done by popping the contents of the current stack or it 
may nave been due to copying the contents of another register to PC However it 
happened it indicates that the value copied to PC was wOrnG. It is also certainly 
possible that the instruction should not have been executed at the time it was (a 
common programmer error). To determine the truth, one has to figure out the 
exact instruction that put the bad value in PC. It is tricky enough to warrant some 
discussion, since PC is the program counter; and it isn’t well enough to tell you 
where the most recently executed instruction is. 


Do Not Do This At Home—We’re Professionals 

Theoretically, let s try to intentionally blow up the works. You should not participate 
in the next three simple exercises, because it is your machine, and these exercises 
are guaranteed to leave the machine in a bad state. So, just watch. 
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We start an application and break into TMON at an arbitrary location. We change 
the value of the program counter—by definition, an even value—into an odd value 
by directly editing the PC using a register window. We then exit TMON. TMON 
will immediately kick back in and display the following message: 

The program counter must be even 

OK, it was waiting for that; so, let’s try something else. We replace that old address, 
and set some breakpoints on JMP (AO) instructions. We let the program run until it 
stops at one of the JMP breakpoints. When it does, we change the return address in 
register AO into an odd value and then exit TMON, forcing the JMP (AO) to 
execute. The following message appears: 

Address error. PC = $007AA52C 
Supervisor fetch at $0070924D 

An exception will occur before the JMP (AO) completes, reactivating TMON. In this 
case, the program counter was not changed; and no register values were changed. 
Based upon this, odd address detection seems pretty good—but wait! 

Once again we restore the proper old address, this time to AO, and set up another 
glitch: breaking just before executing an RTS instruction, we change to an odd 
value the address at the top of the current stack— the memory location that is 
indicated by (A7). 

After exiting TMON, an exception will occur before execution of the RTS 
instruction is done. Cleaning up after this one is more involved. Because, the old 
top of stack has likely been modified, and the contents of A7 was incremented by 4, 
before the exception tripped. Although odd address detection is good, it doesnt 
always come early enough in the execution of a machine instruction for you to 
avoid an ExitToShell, Reboot or to type the correct values for modified locations 
before moving onward. We play it safe and reboot the machine. When you are 
solving a vicious problem, you might opt (dangerously) to adjust A7 and the stack 
on one of these to continue the hunt; TMON will not let you continue without 
changing something. 

To summarize, in these three examples of maliciously subverting the program 
counter with odd addresses, two of the three detect a problem soon enough for you 
to recover from them easily; the third does not. Since the change is an easily 
detected odd address, they make for excellent simple examples. 

If we were to introduce a bad even address rather than an odd one, error detection 
becomes much mo re... ahem... involved. There is sometimes no quick way to 
determine whether an even address is bad, so an exception isn t generated 
immediately. The instruction with the bad address is executed, and the program 
continues to follow the road of meimufado until an exception is eventually 
generated. The trail can become cold in a matter of several instructions. 

With a little ingenuity, it is possible to create some script commands and menu 
items to check for specific conditions to be true or false—at the touch of a menu 
button. Having TMON do the work for you at your prompting is one step short of 
having TMON do it automatically, warning you only when it happens. An example 
of more automated usage involves the elaborate forms of the breakpoint and trap 
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commands which can check for specific conditions to be present, and trigger as the 
situation warrants. 

For the Want of a Machine Instruction Recorder... 

In a more ideal universe (one that still had assembler as a language), you would be 
able to back the computer up a few instructions until you were able to see when and 
where the problem happened. Being able to do this makes debugging much easier. 
There are devices in common use today, called hardware emulators, that are fast 
enough to record the execution of machine instructions in real time. The most 
recently executed 20000 instructions or so would be stored in the emulator’s 
memory, and you could look at the list if the program (or hardware) bombed. 

Hardware emulators that are fast enough to record the passage of 68020 
instructions at full bore are pricey items, costing much more than a copy of TMON. 
Hardware emulators are in common use where custom hardware and firmware are 
being developed for applications with realtime concerns. Implementing an 
instruction record feature in software could have been done in TMON, but the cost 
would have been slowing the application down to a snail-like crawl. 

Trap and Breakpoint Recording 

TMON compromises with reality by providing a record facility where the execution 
of selected traps and breakpoints can be recorded. Trap record is a far cry from 
recording every machine instruction, but it is still handy as all get out. 

You will recall that on the Macintosh, an application executes a trap whenever a 
ROM or a toolbox function call is made. This happens infrequently, so if TMON 
was to intercept any access to the trap dispatch routines to record selected trap 
calls, program execution wouldn’t drastically slow down. In fact, there is time to be 
picky about which traps are to be recorded. 

TMON also provides ways to create breakpoints, which can be assigned anywhere 
in memory. Any number of breakpoints can be created, although performance is 
likely to suffer for it. 

What good is recording only a fraction of the instructions that are being executed? 
In the simple debugging example described here, you may not have a list of the 
most recently executed instructions leading up to the bad address upon the 
corruption of the program counter. But, you can easily obtain the identity of the 
most recent trap calls. Trap calls on the Macintosh are usually made frequently 
enough to start tracing execution of the code where that last trap call or breakpoint 
is made in the application. You may have to restart the application, wait for a while, 
set a breakpoint at the important address, wait until the breakpoint is encountered, 
and then begin tracing the execution of the code. Although these steps require 
much more knowledge of TMON and the application than providing the capability 
of recording every executed machine instruction, it is significantly faster and more 
practical. 

Closing In 

Using a combination of trap (and breakpoint) record list inspections, traces, setting 
and encountering trap watches and breakpoints, it is possible to cover the span of 
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code starting from the last known and easily referenced trap call and “sneak up 
behind” where the bad program counter contents manifested. By doing this, we are 
effectively performing these steps: 

• Encounter a fatal problem 

• Roughly estimate how the program got there 

• Take as small a step “backward” as possible by starting again 

and stopping before we hit the problem area 

• Trace through the rest of the code up to where the problem is 

Expert knowledge of TMON and how Macintosh programs execute is worth a great 
deal to make intelligent time-saving decisions on where to set breakpoints, when to 
execute freely, and when to single-step. Trap Record is not the only place where 
useful context is available, but it is one of the simplest. These tools help you 
perform a rapid divide-and-conquer approach to finding bugs. 

After debugging for a while, some things become obvious, and you’ll never have to 
look at them. Especially if you are new at debugging, take it easy, go slow, and poke 
around. It is important that you understand what the correct values look like. You 
will be riding rapids in a kayak without a paddle if you can’t explain what the 
registers should contain. 

10/2/90 2:34 AM - Bus Error crash. PC contains odd address; A3 contains same 
value, A5 correctly points to globals, A6 points to last stack frame 
(DoEachCellView). 

Time Critical Problems 

This manual mentions elsewhere that a Macintosh application may behave 
differently when placed under a high-powered microscope such as TMON. This 
symbolic debugger is designed to be innocuous: harmless as possible to its 
surroundings. TMON’s features vary in CPU-intensity. Some may cause enough of 
a performance hit to prevent the program from operating properly, confusing you. 
You may see a problem crop up due to the slowdown, rather than due to a bug in 
the application. 

It means that you have to exercise some skill when using the faster features of 
TMON and narrow down where a problem may be before turning on one of the 
time-consuming features. The slower features easily disaffect performance when 
they are left on for a long time, but if you narrow down the search without relying 
upon them, then they won’t have to be left on long enough to cause critical timing 
problems. 

One of those slow features is the TMON Trap Recorder, which captures the 
currently executed A000 trap in a circular buffer in memory. This means that the 
TMON monitor has to execute some code after every A000 trap to “capture the 
moment.” A program with this weight tied to its feet will not win any speed awards, 
but it may provide the information you need. You can avoid problems by turning on 
and recording only the traps and breakpoints you really need to watch. 

When a serious problem activates the TMON monitor, the cause of the problem 
may have struck several hundred instructions before a detectable system error was 
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encountered. The recorder provides a way to remember what the application did for 
some time, perhaps several thousand instructions. You can set the size of the 
recorder buffer by typing 

/BufferSize=value 

where value can be any number of bytes that will fit in memory. 

The recorder alone is excellent by itself when you use it to solve simple elusive 
defects. However, there are classes of bugs that will be limited by the simple use of 
the recorder. 

Sparse and Subtle Problems 

If you have to go all the way to the beginning of a large buffer to see anything, it 
means that you may have to do something else to narrow down the problem. Using 
the recorder alone will take too much time. 

A software defect does not have to cause a catastrophe: the exception that triggers 
the appearance of the TMON control menu may not occur. 

A problem may not happen for hours, days, or weeks; so simply leaving the 
recorder on may not be practical. In fact, it may delay the appearance of the 
problem. You may want to do something to artificially encourage a glitch. 
Scrambling the heap does a good job of this if there is a handle dereferencing 
problem to track down. 

There are also problems that can cause so much grief that TMON is effectively 
attacked from behind and destroyed before it can react. These problems are mighty 
rare, but they can happen. When they do, everything freezes and neither TMON 
nor the Dire Straits alert will appear; you will have to restart the machine and try 
again. 


Customizing TMON for Testing 

TMON Pro’s configurability and extensibility may not be an obvious immediate 
advantage. Since it is possible to create new menu items and scripts, it is possible to 
use TMON as a powerful test bench for new hardware development. TMON, in 
fact, makes a dandy platform for expressive new hardware testing and control. 

For example, a Macintosh II card is likely to have memory-mapped I/O. It is a 
simple matter to create scripts which read and write to specific addresses in order 
to test and control a NuBus card. Then, it is easy creating special menu items 
(removing other menu items if the control menu becomes too crowded) to perform 
repetitive tasks. 

One good suggestion is to define record types which describe the entire range of 
memory mapped 1/0 used by a card. TMON memory windows can then be used to 
display this low-level card interface in a high-level fashion—as though it were no 
different from any other record in memory. 
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